Drift — command-line options

What each option does and when to change it. The same texts are printed by driftfinder --help --lang en and shown by the «?» buttons in the web interface. The defaults suit most series.

Input data and results

--lights LIGHT frames of the series: a folder, a mask (*.fits) or a list of files. All frames of one field; several nights in a row are fine — they are split by the --session-gap pause. At least 3 frames per night are needed; 10 or more for a confident search for faint objects.

--darks DARK frames with the same exposure and temperature as the LIGHTs. Without them hot pixels and thermal signal stay on the frames; cosmetic correction removes some hot pixels, but darks are better. If the exposure differs, the log shows a warning: the dark is subtracted as is and the calibration will be inaccurate.

--flats FLAT frames: remove vignetting and dust. Without flats the background rises at the field edges and dust gives rings that can interfere with the search for faint objects and variable photometry.

--darkflats DARKFLAT frames with the flat exposure: subtracted from the flats. Without them the bias is not removed from the flats and the vignetting correction is inaccurate; if you did not take darkflats, you can give bias frames here.

-o, --out — default asteroid_results Folder for the results: candidate tables, animations, overview image, log. If the folder already exists, files are overwritten — use different folders to compare settings.

--prepare-only Stage 1: calibration and alignment only, no search. The result (session, previews and frame metrics) is saved to <out>/_session. Handy for reviewing the frames, dropping bad ones (clouds, trailing) and then searching with --resume — this is what the web interface does.

--resume Stage 2: search on a session prepared with --prepare-only (path to the _session folder). Lets you try different search settings without repeating calibration and alignment.

--use-frames — default all Which session frames to search with --resume: all — every frame; otherwise comma-separated file names or @file.json with a list. Exclude frames with clouds, trailing or light pollution — they cause false detections and spoil the threshold.

--no-gif Do not make candidate animations (GIF). Finishes faster when there are hundreds of candidates (e.g. when experimenting with thresholds), but checking candidates without animations is awkward.

--known-gif Make animations of known asteroids the search did not find (frames are cut along the JPL prediction). Useful to see whether the object is visible at all and why it was missed; with many faint known objects in the field it creates many files.

--vsx-gif Make animations of known VSX variables the search did not flag. Lets you check by eye whether the brightness changes; there may be many files.

--save-aligned Save the aligned calibrated frames as FITS (aligned_###.fits). For checking calibration and alignment or for processing in other software. Takes a lot of space.

--save-residuals Save the difference frames «frame − static sky» as FITS. Diagnostics: they show what remains after subtracting the stars — moving objects, bright star residuals, gradients. Takes a lot of space.

Performance

--jobs — default 0 Number of parallel processes. 0 — automatic: all cores but one, limited by free memory (≈0.6 GB per process on 16 MP frames). Reduce it if the computer is needed for other work or memory runs short; raising it above the number of cores is pointless.

--gpu — default none Where to run synthetic tracking (the longest part of the search): none — on the CPU; auto — the first NVIDIA GPU found; or an identifier from --list-gpus (cuda:0, cuda:1…). Only NVIDIA GPUs are supported. A GPU speeds up the velocity search tens of times; the result is the same. If the GPU gives an error, go back to none.

--list-gpus List the GPUs the program can use for synthetic tracking and exit. Pass an identifier from the list to --gpu.

--lang Language of messages, the log and this help: ru — Russian, en — English. By default — from the DRIFT_LANG variable, otherwise English.

Calibration and alignment

--cfa — default auto Raw frame of a color camera (Bayer matrix): after calibration every 2×2 pixels are summed into one (superpixel), resolution on each axis is halved. auto — by the BAYERPAT header keyword. yes — if the header has no BAYERPAT but the frame shows a grid of colored pixels; no — for a mono camera or already debayered data.

--bin — default 1 Additional software N×N binning after calibration (and after the color camera superpixel). 2 — 4 times fewer pixels: faster and higher SNR per pixel, but lower resolution. Makes sense with strong oversampling (star FWHM above ~5 px) or very large frames; with FWHM 2–3 px do not bin — faint objects will merge with stars.

--no-cosmetic Do not remove hot and cold pixels (cosmetic correction). Turn it off only for diagnostics or if it spoils very sharp stars (FWHM < 1.5 px). Without it, single hot pixels not removed by darks give false detections.

--bg-box — default 64 Cell size (px) for estimating and subtracting the background on each frame. Smaller (32) removes light pollution gradients and moonlight better but «eats» extended objects (comet coma, nebulae) larger than ~the cell. Larger (128–256) preserves extended structures but copes worse with a rapidly changing background. Increase it for large comets.

--fwhm Star full width at half maximum, px. Usually measured automatically from the frames. Set it manually if the automatic value is wrong (it is shown in the log): strongly defocused or elongated stars, few stars in the field. Many search tolerances depend on FWHM.

--align-stars — default 60 Number of brightest stars for coarse triangle alignment. Increase (100–200) if alignment finds no match in dense fields or with a large shift/rotation; decrease (30) if the field has few stars.

--align-order — default 3 Polynomial degree of the fine alignment on all stars. 3 — accounts for distortion and field rotation; 0 — shift, rotation and scale only (for a narrow field of a long-focus telescope). Raise to 4–5 for wide-angle lenses with strong distortion (large RMS at the edges in the log); lower it if there are few stars and the alignment «floats».

--interp — default 3 Interpolation when resampling a frame to the common grid: 3 — cubic spline (more accurate, keeps the star shape), 1 — bilinear (faster, slightly blurs, but no «ringing» around hot pixels and very sharp stars).

Search on single frames

--nsigma — default 4.0 Source detection threshold on the difference frame (frame − static sky), in noise sigmas. Lower (3–3.5) — more faint objects, but more noise detections too (slower linking, more false tracks). Higher (5–6) — if there are many false detections in bright fields. Faint objects are better found by synthetic tracking than by lowering this threshold.

--min-pix — default 3 Minimum pixels above the threshold in one detection. Cuts single hot pixels and cosmic rays. Increase with a large FWHM (>4 px), decrease to 2 with very sharp stars or after binning.

--max-det — default 6000 Maximum detections per frame (the faintest are dropped). Protects against an explosion of linking time on frames with clouds or light pollution. Increase for very dense star fields if the log shows the limit is reached and objects are lost.

--star-ratio — default 2.0 A detection is dropped if the stack star at that spot is N times brighter: it is a star residual after subtraction (seeing, guiding). Decrease (1.5) if there are many false tracks on stars; increase (3–5) if asteroids disappear when passing over stars.

--max-on-star Maximum fraction of track points lying on stack stars (0..1). Default — the star coverage of the field + 0.3, within 0.5–0.8. Decrease for dense fields (Milky Way) if tracks «jump between stars»; increase if objects in front of a cluster are missed.

--min-det Minimum frames of one night on which the object must be detected. Default max(4, half the night's frames). Decrease if the object is hidden by stars or clouds for part of the night; increase if there are many false tracks from random noise coincidences.

--max-step — default 30.0 Maximum object shift between neighboring frames, px. Sets the speed limit of the frame-based search. Increase for fast near-Earth objects (NEO) or sparse sampling; decrease to speed up linking in dense fields.

--min-motion Minimum object shift over the whole night, px (default 1.5·FWHM): slower is considered static. Increase if static stars with changing seeing give false tracks; decrease for very short series and distant slow objects.

--tol Tolerance of track points from a straight line, px (default max(2, 0.7·FWHM)). Increase with poor guiding and inaccurate alignment or for fast NEOs with a noticeably curved path; decrease to cut random noise chains.

--frames-stack-snr — default 5.0 A track found on single frames is checked by stacking the frames along it: the stack SNR must be at least this. Random chains of noise detections give no signal in sum. 0 — do not check. Decrease if real objects are rejected with few frames.

--low-nsigma — default 0.0 Threshold of the second, sensitive detection pass, σ (0 — off). E.g. 2.5 looks for faint objects on single frames; every track is then checked by stacking. Usually not needed: synthetic tracking finds faint objects better. Use it if tracking is off or the object is faster than its speed limit.

--low-min-det Sensitive pass: minimum frames of the night with the faint object (default max(5, 18% of the night's frames)).

--low-hit-prob — default 0.03 Sensitive pass: allowed probability of a random noise detection falling into the tolerance window; sets the maximum detection density per frame. Lower — stricter and faster; higher — more sensitive but more false chains.

--low-max-cand — default 5000 Sensitive pass: maximum candidate tracks checked by stacking (longest and brightest first). Limits the run time.

--stack-snr — default 7.0 Minimum SNR of the image stacked with a shift along the track to confirm a faint object of the sensitive pass. Also the «visible in the stack» threshold for known but not found objects. Lower — more faint candidates and more false ones.

--stack-snr-indep — default 4.5 Minimum SNR of stacking only the frames where the object was NOT detected: an independent confirmation, protects against tracks assembled from noise.

Synthetic tracking (shift-and-stack — faint objects)

--no-track Synthetic tracking (--no-track turns it off): trying velocities and stacking all frames of the night with a shift. Finds objects invisible on single frames (1–2 magnitudes fainter). The longest part of the search (a GPU speeds it up, --gpu). Turn it off for a quick check of bright objects.

--track-snr — default 7.0 Base SNR threshold of synthetic tracking. The actual threshold for each night is calibrated on the noise (by shuffling frames) and is never below this. Raise it (8–9) for false faint candidates; lowering below 6 is pointless — the calibration sets the threshold.

--track-vmax-arcmin — default 1.5 Maximum velocity searched, arcsec/min (converted to px/h by the scale). 1.5″/min covers almost all main-belt asteroids; increase for NEOs (3–10), but the time grows quadratically with speed.

--track-vmax Same as --track-vmax-arcmin but directly in px/h (if the scale is unknown).

--track-min-px Minimum object shift per night, px: the lower speed limit = this shift / night length. Default 4·FWHM within 5–10 px. Slower is indistinguishable from a star with changing seeing. Decrease for distant slow objects (trans-Neptunian objects, comets far from the Sun) in good seeing; increase for false candidates on stars.

--track-smear — default 0.5 Velocity grid step: how far (in FWHM) an object may «drift» at the series ends because of an inexact velocity. Smaller (0.3) — slightly more sensitive but the search takes several times longer; larger (0.7–1) — faster, faint objects lose SNR.

--track-max-vel — default 20000 Limit on the number of velocity options; above it the grid step is coarsened. Protects against a very long search with long series and a high maximum speed.

--track-fa — default 1.0 How many false noise peaks per night are expected at the chosen threshold (the threshold is set from the noise calibration). Fewer (0.3) — stricter, fewer false candidates; more (3) — more sensitive, but more false ones to look through.

--track-slow — default 2.0 Velocities up to this many minimum velocities count as slow and get a separate, usually stricter threshold: slow «objects» are most often star residuals and seeing.

--track-zero — default 0.85 Static check for slow candidates: if stacking without a shift gives at least this fraction of the SNR, it is a static faint star. Lower it (0.7) if stars still get through; raise it (0.95) or set 0 (no check) if slow objects are lost.

--track-thalf — default 0.4 The candidate's SNR in each half of the night (by time) must be at least this fraction of the total (≈0.7 for a real object). Cuts «signal» gathered on part of the path (star residuals in dense fields). Lower it if the night is uneven (clouds in one half); 0 — no check.

--track-trim — default 0.25 Fraction of the brightest frames without which the candidate must keep a noticeable signal. Cuts candidates whose signal came from 1–2 frames (satellite, cosmic ray, flash). 0 — no check.

--track-max-cand — default 2000 Maximum synthetic tracking peaks checked in detail. If the log shows the limit is reached, it usually signals a data problem (clouds, poor alignment), not a reason to raise it.

--edge-cover — default 0.5 Objects at the field edge: minimum fraction of the night's frames in which the object must be inside the field (the rest are beyond the edge, e.g. because of mount drift or because the object entered or left the field mid-night). Such frames are ignored both in stacking and in the «minimum frames» requirement. Lower it (0.3) to catch objects crossing the edge at the start or end of the night; raise it (0.7) if false candidates appear at the edges.

--edge-snr — default 1.0 Objects at the field edge: how much higher the synthetic tracking SNR threshold is for a path that approaches the data edge or is not visible in all frames. At the edge the «static sky» is built from fewer frames and the flat is worse — there are more noise peaks. 0 — same threshold as in the center (more finds at the edge and more false ones); raise it (1.5–2) if there are false candidates at the edges.

--unstable, --track-unstable — default 2.5 Pixels whose brightness scatter in time exceeds the noise this many times (halos and residuals of bright stars with changing seeing, diffraction spikes) are excluded from the search. Decrease (2.0) if there are many false candidates near bright stars; increase (3–4) if objects disappear in star-rich fields. Note: the coma of a slow comet is «unstable» too.

Comets

--no-comets Comet search — moving objects with a coma (fast ones by differences of night parts, slow ones by the nucleus shift of an extended source). --no-comets turns it off: if the comet search gives false detections on your data or you want to save a few seconds.

--comet-snr — default 6.0 Fast comets: SNR threshold of a diffuse blob in the difference of night parts (each night is split into 3 parts). Lower it (4–5) for faint comets; raise it (8–10) if nebulae and gradients give many blobs (hundreds of «blobs in night parts» in the log).

--comet-coma — default 0.01 Minimum coma brightness in the 1.5–3 FWHM ring around the nucleus, as a fraction of the nucleus brightness. The threshold rises automatically if the image stars have wide wings (scattering, poor seeing). Lower it for comets with a very bright point-like condensation and a faint coma; raise it if ordinary asteroids are marked as comets.

--comet-coma-max — default 0.35 Maximum coma brightness as a fraction of the nucleus (fast comets and the check of found objects). Above it this is not a nucleus with a coma but a background patch on a nebula. Raise it (0.6–0.9) for comets with a wide bright condensation instead of a nucleus.

--comet-sig — default 4.0 Minimum coma significance above the background, σ. Lower it (3) for faint comets; raise it (5–6) if asteroids near bright stars are marked as comets.

--comet-stack-snr — default 6.0 Minimum SNR of the central condensation when stacking frames along the comet path (half of it for slow comets). Protects against random coincidences of background blobs. Lower it for comets without a distinct nucleus.

--comet-seed-snr — default 20.0 Slow comets: minimum SNR of the condensation of an extended source to check whether its nucleus moves. Lower it (10) for faint slow comets (the check takes longer).

--comet-move-sig — default 8.0 Slow comets: minimum significance of the nucleus shift over the night, σ. Tells a comet from a galaxy (whose core stays put). Lower it (5) for very slow comets on a short night; raise it (12) if galaxies with bright stars nearby get marked as comets.

--no-jpl-comets Query known comets from JPL — separately from asteroids and without a brightness limit (comets have no V magnitude in the asteroid sense, and JPL does not return them with --vmag-lim). --no-jpl-comets turns the query off (e.g. if it is too slow for a wide field).

Nights and linking

--session-gap — default 3.0 Pause between frames (hours) after which a new night (session) starts. The search runs on each night separately, then tracks of different nights are linked. Decrease it if there was a long break within one night (clouds) and the object moved far meanwhile.

--link-dv — default 0.15 Allowed relative velocity difference when linking tracks of different nights into one object (0.15 = 15%). Increase it for close objects with a noticeably changing speed; decrease it if clearly different objects get linked.

Astrometry (plate solving and Gaia refinement)

--solve — default auto Plate solving of the reference frame (needed if the header has no WCS): auto — ASTAP, on failure the built-in Gaia DR3 solver and astrometry.net; astap — ASTAP only; gaia — built-in only (internet required); astrometry — local solve-field; none — do not solve (no coordinates and no identification of known objects).

--astap Path to astap.exe or astap_cli.exe if the program did not find it (usually C:\Program Files\astap). Without ASTAP the fallback solvers are used.

--astap-db Folder with the ASTAP star database (D50, D20, V50…) if it is not in the ASTAP folder. A 0.6–6° field needs D50 or D20, wide fields need W08.

--ra Approximate field center in right ascension (degrees or HH:MM:SS) if the header has none. Makes plate solving faster and more reliable.

--dec Approximate field center in declination (degrees or ±DD:MM:SS) if the header has none.

--pixscale Image scale, arcseconds per pixel (before the program's binning). Needed if the header has no WCS and no focal length with pixel size: speeds up plate solving and allows speeds in ″/min.

--solve-radius — default 30.0 Search radius around the field center hint, degrees. Decrease it if the center is known precisely (faster); increase to 180 if the hint may be wrong.

--solve-timeout — default 300.0 Plate solving time limit, seconds. Increase it for a blind search without a center hint.

--no-refine-wcs Astrometry refinement with Gaia DR3: accounts for lens distortion and improves the accuracy of coordinates and identification to a fraction of an arcsecond; internet required. --no-refine-wcs turns it off — without internet or if it gives an error.

--refine-order — default 3 Polynomial degree of the Gaia astrometry correction. 3 — usual; 4–5 — for wide-angle lenses with strong distortion; 1 — for a narrow field and few stars.

Known asteroids and comets (WCS and internet required)

--known — default jpl Source of known small bodies: jpl — the JPL Small-Body Identification service (WCS and internet required), none — do not identify.

--observatory MPC observatory code for accurate position predictions (parallax matters for close objects). Default — latitude/longitude from the header (SITELAT/SITELONG), otherwise the geocenter: for near-Earth objects the prediction may then be off by arcminutes.

--vmag-lim — default 17.0 Limiting V magnitude for querying known asteroids. Set it 0.5–1m fainter than your series actually reaches: otherwise faint known objects will not be identified and will show up as «new». 0 — no limit (slower, many invisible objects).

--jpl-retries — default 10 How many times to retry the JPL query on a network or server error. Increase it with an unstable internet connection.

--catalog-retries — default 10 How many times to retry queries to the VizieR catalogs (Gaia DR3 — for plate solving and astrometry refinement, VSX — for variable stars) on a network or server error. Each attempt goes through all VizieR mirrors, the pause between attempts grows up to 15 s. Increase it with an unstable internet connection; decrease it (1–2) if the catalog is known to be down and you do not want to wait.

--known-radius — default 10.0 Radius for identifying a candidate with a known object, arcsec. Increase it (20–30) if the field astrometry is inaccurate or the images are old (prediction errors grow with time); decrease it in asteroid-rich fields so as not to mix up neighbors.

--known-radius-vel — default 600.0 If the candidate's motion matches a known object's motion, identify it even with an offset up to this value, arcsec (helps with inaccurate astrometry). 0 — do not use.

Variable stars (experimental)

--variables Search for variable stars (experimental): photometry of all stars on all frames, search for stars whose brightness changes more than noise and seeing, cross-check with the VSX catalog. False detections are possible; works better on several nights.

--var-snr — default 10.0 Star detection threshold on the stack for photometry, σ. Lower it to measure fainter stars (slower, more noise).

--var-min-snr — default 8.0 Stars fainter than this per-frame SNR are not searched: their noise exceeds real variability. Lower it to search for faint large-amplitude variables.

--var-halo — default 12.0 Stars closer than this many FWHM to a saturated star are not measured: the halo changes with seeing and mimics variability.

--var-max-stars — default 20000 Maximum stars for photometry (the brightest). Limits the time in dense fields.

--var-sigma — default 2.0 A star is variable if its brightness scatter is this many times larger than for stars of the same brightness. Raise it (3) for false variables; lower it (1.5) for small amplitudes with good photometry.

--var-min-amp — default 0.05 Minimum amplitude of the brightness change (between the 5th and 95th percentiles), magnitudes. Raise it to keep only noticeable variables.

--var-eta — default 1.0 Maximum von Neumann ratio (≈2 for noise, less for a smoothly varying star). Lower it (0.7) — smooth changes only; raise it (1.5) for fast variables changing between neighboring frames.

--var-max — default 300 Maximum candidates in the report (best by significance).

--var-local — default 10 Local brightness correction from this many nearest comparison stars (accounts for uneven transparency and vignetting across the field). 0 — global correction only.

--var-bad-frame — default 2.5 A frame is excluded from photometry if the comparison star scatter is this many times above normal (clouds, trailing).

--var-trim — default 0.6 Without the two most deviant frames the scatter must stay at least this fraction of the --var-sigma threshold: cuts «variability» caused by one or two bad frames.

--var-bkg — default plane Background around a star: plane — a tilted plane (for nebulae and gradients), median — the annulus median (simpler, for a clean background).

--var-min-step — default 0.15 Minimum change of the mean brightness from night to night, m. For several nights this is the main sign of a real variable.

--var-step-typ — default 3.0 The night-to-night change must be this many times larger than usual for stars of the same brightness (all stars change a little because of different weather).

--var-step-snr — default 5.0 Significance of the night-to-night change in errors of the nightly means.

--var-any-night Require a night-to-night brightness change (the main sign of a variable with several nights). --var-any-night lifts the requirement: variables changing within a night (eclipsing, short-period) are searched for too; use it with one night — there will be more false ones.

--var-max-corr — default 0.7 A light curve similar (correlation above this) to the curves of several other stars is considered systematics (clouds, seeing), not variability.

--var-max-ellip — default 0.15 Stars elongated more than typical by this value are not measured (close doubles, star + galaxy).

--no-vsx Cross-check with the AAVSO VSX variable star catalog: which known variables are in the field and whether they could be measured. --no-vsx turns it off (no internet).

--vsx-mag — default 16.0 Query known VSX variables brighter than this magnitude.

--vsx-radius — default 10.0 VSX identification radius, arcsec.