DSPX's start-up options and the command-line tools that come with it
DSPX can be started with options, and it comes with command-line tools that run its engines without the window:
converting images, stacking and calibrating frames, registering them, running a whole pre-processing session, building the sky catalogs
and the files for the blind plate solver. This chapter lists the options of the program, then each tool with what it is for, how it is
called, and its main options. Every tool prints its complete list of options with --help.
DSPX is started as DSPX [options] [files]. Anything on the command line that is not an option is a file, and opens as if it
had been chosen in : images, saved processes (.dsproc, .xpsm), pre-processing
sessions (.dspxpre) and projects (.dspx) (Opening Images).
--version: Prints the program's name, version and release, DSPX 1.0.0 Beta 1 for example, and exits. On Windows it
writes to the console the program was started from.
--help, -h: Prints the options listed here, one line each, and exits.
--language <id>: Runs the program in that language for this session. It is not remembered; the choice that is
remembered is made in . The ids are en_US, de_DE,
es_ES, fr_FR, it_IT, ja_JP, pt_BR and zh_CN
(Localization).
--languages: Prints the languages as the Language list shows them, one per line with the id first, and the language in
use, and exits. With --language it prints them in that language. The languages added from translation files are listed too.
--import-translation <file>: Checks a translation file (a filled .ts, or a language pack), prepares it, adds the
language to the Language list and exits. It prints how many texts were taken and which were dropped and why
(Translating DSPX into Your Language).
--remove-translation <id>: Removes a language that was added from a translation file, by its id, and exits. A built-in language cannot
be removed.
--export-translation-template <folder>: Writes the English texts of this version, the translator's guide and the glossary to the folder,
as Export translation template... does in the Preferences, and exits.
--export-translation-delta <id> <folder>: Writes to the folder a file with only the texts of a language added from a translation file that are
not translated yet, as Export what is left... does in the Preferences, and exits.
--theme <name or id>: Runs the program in a theme for this session, without remembering it. A theme is given
by its name as the Themes list shows it (--theme "Syrup (Dark)"), a theme of our own by its name or the id of its file
(Themes). Six built-in themes also have an id: dsc-light, dsc-dark,
dsc-deep-sky, dsc-granite, night and high-contrast; so do fix-inside-light (Fix Inside (Light)),
syrup-dark (Syrup (Dark)) and psychon-dark (Psycho'n (Dark)).
--first-run-dialog: Opens the Setup Assistant (The First Start)
before the program opens, on any system and even when DSPX already has settings, with every step. The language and the look chosen replace
the ones kept; the look is kept as that theme, DSPX Dark, Fix Inside (Light), PhotonChop (Dark), Syrup (Dark) or Psycho'n (Dark), and no longer follows the system's light or dark mode. A step that is skipped
changes nothing. It is how to see or repeat the window on a computer where it has been shown, and the same window opens from
once the program is running. It is not shown without a screen.
--translations <folder>: Reads translations (.qm files) from a folder before the ones built into the
program. It is for translators who want to try a translation before it is built in; nothing is kept.
--ai-folder <folder>: Takes the AI files from that folder first, for this session: ONNX Runtime from its
bin folder and each AI process's model from lib/<Process>, the layout of the program's own folder. A model the
folder does not have is still taken from the program's own folder. Nothing is remembered; without the option the AI files come from the
program's own folder. The Log says which folder is used, or that the path is not a folder and is not used. Not on macOS, where the
program uses only the AI files inside its bundle (The AI Processes).
--setup-scripts: Sets up the Python that scripts run with, and everything Siril's scripts need on top of it (numpy and sirilpy), as
Set Up... and Add Siril Scripts Support... do in
, and prints the times and the sizes. Giving the command is the consent to the
download (Setting Up Python).
--get-scripts: With --setup-scripts, downloads Siril's scripts repository too, and then checks it for
updates (Siril's Scripts Repository).
--run-script <file.py> [--python <python>] [options] [-- script arguments]: Runs a Python script with no window, and exits: the same run as
(the same working copy, one history step, the same refusals), on a synthetic image or on --file <image> (the other options are
--image WxHxC, --type float|word, --content stars|ramp|flat|noise, --solved, --no-image, --param id=value,
--confirm yes|no, --save <file>, --cli, --own-sirilpy, --timeout <seconds> and --work <folder>). The Log goes to the standard
output, the last line is DSW_SCRIPT_RESULT with a JSON summary, and the exit code is 0 when the script ended, 1 when it failed or was refused, 2 when it was stopped
and 3 for a mistake in the command line. For a parameter of the kind image (Open Images as Parameters),
--param id=NAME names the open image the run has (synthetic, or the name of the --file image), and --param id=PATH opens an image file as another image of the
run, named by its file, and picks it; a parameter not given takes its default (@front is the image of the run), and the summary lists the images picked, each with its history, under images. The Python is the one given with --python, else the one named by DSW_PYTHON, else DSPX's own; the choice in
Preferences is not used. The license applies as in the window: without one, a script cannot change an image, run a process or save a file.
Without --work, the run's folders are in a private folder of ours in the system's temporary folder. A --work folder must be ours: on
Linux and macOS, a folder that belongs to another user, a link, or a folder other users can write to is refused.
--list-processes-json [file] lists every process with its settings as JSON.
The program has other options that run its self-tests and take its documentation pictures. They exist for development and are not described here.
DSW_DATA_DIR puts what the program keeps for itself (the Python for scripts, for example) in the folder it names, and
makes the program read and write no settings of the usual kind. With it a run starts clean and leaves nothing behind it.DSW_CACHE_DIR names the cache folder of the pre-processing engine: the frame records and registrations are in its
frames folder, the raw frames in raw and the masters in masters, as in the default place. The program's own
setting, , Cache folder, sets it the same way when the program starts,
unless the environment has it already: the environment wins. The undo steps of the open images are kept in its undo folder. DSW_RAW_CACHE_DIR and DSW_MASTER_CACHE_DIR name the
folder of one cache alone. The tools' --cache-dir names, for one run, the folder of the frame records and registrations (the masters
go in its masters folder).DSW_AI_DIR names a folder of AI files, laid out as for --ai-folder, that is looked at before the
--ai-folder folder and the program's own (The AI Processes).The tools are programs of their own, called from a terminal. They use the same engines as the processes of the window, so a tool and
the matching process give the same result from the same settings. They write English, read the same file formats (Images and Files), print what they do, and report a failure by a status other than 0. Giving no arguments, or
--help, prints a tool's usage. A tool needs the same processor as DSPX (System
Requirements).
The pre-processing tools share conventions. Files are given one by one, as wildcards, or in a list file written @list.txt
(one path per line). They work in one of two modes: --mode fast, the default, and --mode parity, which does every
step as PixInsight's process of the same name does. --threads sets the number of threads (all by default), --cache-dir
and --no-cache control the cache of per-frame records, --report file.tsv writes a table of the run, and
--quiet prints less. A switch can be turned off by --no-<name> or given a value, --clip-low false.
Converts an image from one format to another, or describes files.
dsw_convert <in> <out> [--type u8|u16|u32|f32|f64] [--compression <name>] [--quality 1..100]
[--stretch auto|linked|none] [--no-keywords]
dsw_convert --info <file>...
--type: The sample type written: 8, 16 or 32-bit integer, or 32 or 64-bit floating point. The default is the image's.
--compression: TIFF's: none, lzw or deflate.
--quality: JPEG's quality.
--stretch: Save as displayed: the image goes through an automatic screen stretch, per channel (auto) or with the
channels linked (linked), the way the screen shows it, as Save Options does. none saves the data as
they are.
--no-keywords: Does not write the FITS keywords as text in a TIFF.
--info: Prints what each file is: its size, channels, sample type and metadata.
Integrates frames into a master: the master bias, dark and flat frames, from FITS or XISF files, with the rejection and the normalization of Integration. It does not register frames.
dsw_stack [options] --out <master.xisf> <frames...>
--combination: average (the default), median, minimum or maximum.
--normalization: none, additive, multiplicative, additive-with-scaling (the default)
or multiplicative-with-scaling.
--rejection: none (the default), minmax, percentile-clip, sigma-clip,
winsorized-sigma-clip, averaged-sigma-clip, linear-fit, esd or rcr, with their thresholds
(--sigma-low, --sigma-high, --pc-clip-low and the like).
--bias, --dark: A master bias, or a master dark or flat dark, to calibrate every frame with first. It is for flat frames.
--weight-mode, --weight-scale: How the frames are weighted.
--generate-rejection-maps: Writes the rejection maps next to the master.
--out: The master, .xisf or .fits.
Calibrates and measures light frames as Calibration does, with cosmetic correction and the measurements
that later steps use. It writes the calibrated frames only when asked with --write; otherwise it leaves the per-frame records in
the cache.
dsw_calibrate [options] <lights...>
--bias, --dark, --flat: The masters, and --calibrate-bias, --calibrate-dark and
--calibrate-flat to calibrate them first. Dark optimization is on by default (--optimize-darks).
--cosmetic-hot, --cosmetic-cold, --defect-map: Cosmetic correction.
--evaluate-noise, --evaluate-signal: The measurements stored in the records.
--write, --output-directory, --output-prefix, --output-postfix, --output-extension: Write the calibrated frames in 32-bit floating
point, where and under which names.
Registers frames from the star lists of the records: it chooses the reference, finds a transform for every frame (shift, similarity, affine or homography), and writes the table of transforms with each frame's inliers and residual. It reads no pixels of the frames that already have records.
dsw_register [pass 1 options] <lights...> dsw_register [options] --record <file.dswrec | wildcard>...
--model: shift, similarity, affine or homography (the default).
--reference: A frame number (1 is the first) or a file name; by default the program chooses.
--distortion-correction: Adds surface splines fitted to the residuals, with the options of Registration's
distortion correction (--rbf-type, --spline-smoothness and others).
--tolerance, --min-inliers, --iterations: The matching limits.
Does the whole pre-processing of light frames into a master with no file in between: calibration and measurement, registration from the stars, then each frame read again, calibrated as it goes, warped, normalized, rejected and integrated. One-shot color frames and camera raw files are debayered on the way.
dsw_preprocess [options] --out <master.xisf> <lights...>
It takes the options of dsw_calibrate for pass 1, of dsw_register for the registration and of dsw_stack for
the integration, and adds:
--set <name>: Starts a master set, for lights that need other masters (other exposures, nights or flats). The calibration options
after it are its own; the lights after it are calibrated with it.
--interpolation, --clamping: The warp: auto, lanczos3 or lanczos4, and the clamping threshold.
--cfa-pattern, --debayer-method: For one-shot color frames: Auto, RGGB and the other patterns; vng or
bilinear.
--local-normalization: Normalizes locally, with the options --ln-* (Local Normalization).
--drizzle: Drizzles too, with --drizzle-scale, --drizzle-kernel and the other drizzle options; the drizzled
image is written next to the master (Drizzle).
--write-registered: Writes the registered frames.
Runs a pre-processing session from the command line. It reads folders of frames, sorts them as the pre-processing window does, plans the session, and runs it, with Easy mode if asked (Pre-processing).
dsw_session plan <folders or files...> [--out session.dspxpre] [--no-recurse] [--cfa-pattern RGGB]
dsw_session show <session.dspxpre> [--files] [--verbose]
dsw_session run <session.dspxpre | folders or files...> [--out FOLDER] [--mode fast|parity] [--ln] [--drizzle]
[--reference PATH] [--dry-run] [--progress] [--no-cache] [--existing keep-both|replace]
[--keep none|all|KIND,...] [--easy [--goal quality|fast] [--accept-suggestions]]
dsw_session analyze <session | folders or files...> [--out FOLDER]
dsw_session integrate <session | FOLDER> [--out FOLDER]
dsw_session select <session | FOLDER> [--save]
dsw_session facts <FOLDER> [--out FILE.tsv]
dsw_session easy-blueprint [--out FILE.awf]
dsw_session trails <FOLDER | analysis.json> [--sheet OUT]
.dspxpre), the same file the
window saves. show prints a session, with its files if asked.--dry-run says what it would do, --existing decides what happens
when an output exists (keep-both, the default, or replace), and --keep says which intermediate files to keep.--exclude,
--include and --clear change single frames, --set selection.approval=EXPR changes the approval expression, and
--save keeps the choices in the session.A line is printed for each step as it runs. --progress adds the progress of each phase.
Builds, checks and queries the star catalog files that Plate Solve reads, and plate solves an image from the command line (Catalog Files).
dsw_catalog info <file>
dsw_catalog verify <file> [--cones N]
dsw_catalog query <file> --ra --dec --radius [--mag] [--max] [--epoch JD]
dsw_catalog cone --ra --dec --radius --mag [--cache DIR]
dsw_catalog fetch-sky --parts DIR --mag-max M [--mag-min m] [--order K]
dsw_catalog build --parts DIR[,DIR...] --out <file> --mag-max M [--mag-min m] [--order K]
dsw_catalog solve <image> [--object NAME] [--ra --dec] [--scale S] [--focal --pixel] [--offline] [--catalog DIR]
[--blind | --all-sky off|auto|always] [--index DIR] [--save <out>]
dsw_catalog index --catalog DIR --out DIR --bands wide|standard|3-8 [--threads N]
dsw_catalog index-info <file.dscquad>
dsw_catalog index-verify <file.dscquad>
--object or --ra and --dec give a hint, --scale or --focal and
--pixel the scale, --offline keeps it from asking the network, and --blind or --all-sky search the whole
sky with the index files from --index. --save writes the image with its solution.Builds the Gaia spectra file the spectrophotometric calibrations read, from ESA's bulk files of sampled mean spectra and DSPX's own base catalog files.
dsw_spectra build --xp <folder> --base <folder> --out <file.dscspec> [--bin K] [--cone ra,dec,radius] [--threads N] dsw_spectra info <file.dscspec>
--bin: The number of ESA's 2 nm samples averaged into one: 1 keeps all 343, 10 gives 34 bins of 20 nm.
--cone: Only the stars of one cone, given as right ascension, declination and radius in degrees.
The file is written under a temporary name and renamed when it is complete. The two tools that read these files are the processes Spectrophotometric Color Calibration and Spectrophotometric Flux Calibration.
A master dark from a night's darks, with Winsorized sigma clipping:
dsw_stack --rejection winsorized-sigma-clip --out MasterDark_300s.xisf darks/*.fit
A stretched TIFF from a master, in 16 bits, for sharing:
dsw_convert M31.xisf M31.tif --type u16 --compression deflate --stretch auto
A whole night, planned and run with Easy mode:
dsw_session plan Night1 --out night1.dspxpre dsw_session run night1.dspxpre --out Night1_out --easy --progress
The development builds also contain test programs, dsw_core_test and a stand-in for RC Astro's tools. They are for
developers and are not described here.