Command line reference

Every subcommand also accepts -h and --help; valerian itself also accepts -V and --version. Exit status is 0 on success and 1 on any error, with the message on standard error.

valerian

Deep-sky image processing

valerian <COMMAND>

Subcommands:

• calibrate: Calibrate light frames with bias, dark, flat and dark-flat frames
• register: Register frames to a reference and write them on its grid
• stack: Register, normalise, weight and combine frames into one image
• drizzle: Combine dithered frames onto a finer grid with drizzle
• bench: Time the GPU kernels against the CPU code and check they agree
• background: Model and remove the sky gradient of an image
• stretch: Stretch a linear image to a viewable one (MTF, arcsinh or GHS)
• starless: Remove or reduce the stars of an image
• solve: Plate-solve an image and write its world coordinate system (TAN-SIP)
• photocal: Calibrate the colour of an image against Gaia star colours
• info: Describe FITS files, or this build and the machine it runs on

valerian calibrate

Calibrate light frames: subtract the master bias and dark, divide by the master flat and repair hot, cold and dead pixels. Each calibration argument is a file or a directory of FITS files and may be repeated. Several files are combined into a master; a single file whose IMAGETYP says it is a master is used as it is. Each light is written to the output directory as a 32-bit float FITS file with _cal added to its name. Calibration frames are streamed from disk in bands of rows, so memory use follows --memory and not the number of frames.

valerian calibrate [OPTIONS] --output <DIR> <LIGHTS>...

Arguments:

• <LIGHTS>: Light frames: FITS files or directories of them (required; repeatable)

Options:

• --bias <PATH>: Bias frames, or a master bias (a file or directory; repeatable)
• --dark <PATH>: Dark frames, or a master dark (a file or directory; repeatable)
• --flat <PATH>: Flat frames, or a master flat (a file or directory; repeatable)
• --dark-flat <PATH>: Dark-flat frames, subtracted from the flats instead of the bias (a file or directory; repeatable)
• -o, --output <DIR>: Directory for the calibrated frames (required)
• --masters <DIR>: Also write the master frames to this directory
• --scale-dark <SCALE_DARK>: How the dark is scaled to each light's exposure (default off)
  • off: Subtract the dark as it is
  • exposure: Multiply by the ratio of exposure times
  • optimise: Fit the multiplier to the light from its hot pixels
• --rejection <REJECTION>: Rejection used to combine the calibration frames (default auto)
  • auto: Winsorised below 15 frames, sigma clipping to 30, linear fit above. --low and --high change the limits of the scheme it picks
  • none: Keep every sample
  • minmax: Drop the lowest and highest sample
  • sigma: Sigma clipping about the median
  • winsorised: Winsorised sigma clipping: robust with few frames
  • linear-fit: Linear fit clipping: robust when levels vary
• --memory <MIB>: Memory for combining calibration frames, in MiB. The frames are read a band of rows at a time, so the master of any number of frames fits (default 1024)
• --hot-sigma <SIGMA>: Hot-pixel limit: sigmas above the neighbours in the master dark (default 40)
• --cold-sigma <SIGMA>: Cold-pixel limit: sigmas below the neighbours in the master dark (default 12)
• --auto-cosmetic: Without a dark, find isolated hot and cold pixels in each light itself
• --flat-per-channel: Normalise the flat per Bayer colour, so it corrects vignetting and dust but not colour balance
• --debayer <DEBAYER>: Demosaic the calibrated frames to three colour planes (default none)
  • auto: Keep a raw mosaic as it is (calibrate) or demosaic with Malvar-He-Cutler if the frames are Bayer data (register and stack)
  • none: Never demosaic
  • mhc: Malvar-He-Cutler gradient-corrected interpolation
  • bilinear: Bilinear interpolation
• --backend <BACKEND>: The engine for the per-pixel stages: auto (the CPU, as one stage alone is slower on the GPU), cpu or gpu (default auto)
  • auto: A real GPU if there is one, otherwise the CPU
  • cpu: Always the CPU
  • gpu: A GPU (the software adapter if there is no real one), or an error

valerian register

Find the stars in every frame, register them to the sharpest (or the one named), resample each onto the reference grid and write it as a 32-bit float FITS file with _reg added to its name. Pixels a frame does not cover are NaN. Raw Bayer frames are demosaiced first.

valerian register [OPTIONS] --output <DIR> <FRAMES>...

Arguments:

• <FRAMES>: Frames: FITS files or directories of them (required; repeatable)

Options:

• -o, --output <DIR>: Directory for the registered frames (required)
• --reference <N>: Index (from 0, in sorted order) of the reference frame; default the sharpest
• --model <MODEL>: Transform to fit (default similarity)
  • similarity: Rotation, uniform scale and shift
  • affine: Adds shear and unequal scale
  • homography: Full perspective; needs many stars across the frame
• --interpolation <INTERPOLATION>: Resampling kernel (default bicubic)
  • bilinear: 2x2 bilinear: smooth, no ringing
  • bicubic: 4x4 bicubic (Catmull-Rom)
  • lanczos3: 6x6 Lanczos: sharpest, can ring around bright stars
• --debayer <DEBAYER>: Demosaic raw Bayer frames (default auto)
  • auto: Keep a raw mosaic as it is (calibrate) or demosaic with Malvar-He-Cutler if the frames are Bayer data (register and stack)
  • none: Never demosaic
  • mhc: Malvar-He-Cutler gradient-corrected interpolation
  • bilinear: Bilinear interpolation
• --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise (default 5)
• --backend <BACKEND>: The engine for the resampling: auto (the CPU, as one stage alone is slower on the GPU), cpu or gpu (default auto)
  • auto: A real GPU if there is one, otherwise the CPU
  • cpu: Always the CPU
  • gpu: A GPU (the software adapter if there is no real one), or an error

valerian stack

Register the frames, match their sky levels and transparency, weight them by noise and star width and combine them with per-pixel outlier rejection. The result is written as a 32-bit float FITS file with NCOMBINE, EXPTOTAL and the reference in its header. A table with one line per frame is printed. Raw Bayer frames are demosaiced first.

valerian stack [OPTIONS] --output <FILE> <FRAMES>...

Arguments:

• <FRAMES>: Frames: FITS files or directories of them (required; repeatable)

Options:

• -o, --output <FILE>: The stacked FITS file to write (required)
• --coverage <FILE>: Also write the per-pixel coverage (frames used) to this FITS file
• --report <FILE>: Also write the per-frame table to this text file
• --rejection <REJECTION>: Rejection scheme (default auto)
  • auto: Winsorised below 15 frames, sigma clipping to 30, linear fit above. --low and --high change the limits of the scheme it picks
  • none: Keep every sample
  • minmax: Drop the lowest and highest sample
  • sigma: Sigma clipping about the median
  • winsorised: Winsorised sigma clipping: robust with few frames
  • linear-fit: Linear fit clipping: robust when levels vary
• --low <SIGMA>: Lower rejection limit in sigmas, where the scheme has one. With --rejection auto it changes the limit of the scheme auto picks
• --high <SIGMA>: Upper rejection limit in sigmas, where the scheme has one. With --rejection auto it changes the limit of the scheme auto picks
• --weights <WEIGHTS>: Frame weights (default noise-fwhm)
  • equal: Every frame counts the same
  • noise: One over the noise squared
  • fwhm: One over the star FWHM squared
  • noise-fwhm: One over noise squared times FWHM squared: best for point sources
• --normalisation <NORMALISATION>: Level matching (default additive-scaling)
  • none: Leave levels as they are
  • additive: Match the sky level to the reference
  • additive-scaling: Match the sky level and scale by the matched stars' flux ratio
• --reference <N>: Index (from 0, in sorted order) of the reference frame; default the sharpest
• --model <MODEL>: Transform to fit (default similarity)
  • similarity: Rotation, uniform scale and shift
  • affine: Adds shear and unequal scale
  • homography: Full perspective; needs many stars across the frame
• --interpolation <INTERPOLATION>: Resampling kernel (default bicubic)
  • bilinear: 2x2 bilinear: smooth, no ringing
  • bicubic: 4x4 bicubic (Catmull-Rom)
  • lanczos3: 6x6 Lanczos: sharpest, can ring around bright stars
• --debayer <DEBAYER>: Demosaic raw Bayer frames (default auto)
  • auto: Keep a raw mosaic as it is (calibrate) or demosaic with Malvar-He-Cutler if the frames are Bayer data (register and stack)
  • none: Never demosaic
  • mhc: Malvar-He-Cutler gradient-corrected interpolation
  • bilinear: Bilinear interpolation
• --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise (default 5)
• --min-stars <N>: Leave out frames with fewer stars than this (default 20)
• --max-fwhm-ratio <RATIO>: Leave out frames whose FWHM is more than this multiple of the reference's
• --backend <BACKEND>: The engine for the resampling and the combine: auto (a real GPU if there is one), cpu or gpu (default auto)
  • auto: A real GPU if there is one, otherwise the CPU
  • cpu: Always the CPU
  • gpu: A GPU (the software adapter if there is no real one), or an error

valerian drizzle

Drizzle (variable-pixel linear reconstruction) for undersampled, dithered frames. The frames are registered as for stack, then every input pixel is shrunk to a drop of --pixfrac of its side, mapped onto an output grid --scale times finer and spread over the output pixels it overlaps in proportion to the overlap, weighted by noise and star width. Pixels more than --reject sigma from a first-pass result (cosmic rays, hot pixels, satellite trails) are left out of a second pass. Raw Bayer mosaics are dropped as mosaics, each pixel into its own colour plane with no interpolation, so give the calibrated frames from valerian calibrate without --debayer. The result is --scale times as wide and as tall, in the input's units, with output pixels no drop reached left as NaN (--weight-map shows the coverage). It needs a dither of a pixel or more between frames and a dozen or more of them to fill a 2x grid; with too few frames use a larger --pixfrac or a smaller --scale.

valerian drizzle [OPTIONS] --output <FILE> <FRAMES>...

Arguments:

• <FRAMES>: Frames: FITS files or directories of them (calibrated; raw mosaics are fine) (required; repeatable)

Options:

• -o, --output <FILE>: The drizzled FITS file to write (required)
• --scale <FACTOR>: Output pixels per input pixel, linear (default 2)
• --pixfrac <FRACTION>: Side of a drop as a fraction of an input pixel, above 0 and at most 1 (default 0.6)
• --reject <SIGMA>: Reject input pixels this many sigma from the first-pass result (default 4)
• --no-reject: Drizzle every pixel, with no rejection pass
• --weight-map <FILE>: Also write the weight map (coverage of the output) to this FITS file
• --report <FILE>: Also write the per-frame table to this text file
• --weights <WEIGHTS>: Frame weights (default noise-fwhm)
  • equal: Every frame counts the same
  • noise: One over the noise squared
  • fwhm: One over the star FWHM squared
  • noise-fwhm: One over noise squared times FWHM squared: best for point sources
• --normalisation <NORMALISATION>: Level matching (default additive-scaling)
  • none: Leave levels as they are
  • additive: Match the sky level to the reference
  • additive-scaling: Match the sky level and scale by the matched stars' flux ratio
• --reference <N>: Index (from 0, in sorted order) of the reference frame; default the sharpest
• --model <MODEL>: Transform to fit (default similarity)
  • similarity: Rotation, uniform scale and shift
  • affine: Adds shear and unequal scale
  • homography: Full perspective; needs many stars across the frame
• --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise (default 5)
• --min-stars <N>: Leave out frames with fewer stars than this (default 20)
• --max-fwhm-ratio <RATIO>: Leave out frames whose FWHM is more than this multiple of the reference's

valerian bench

Run calibration, the registration warp and the stack's per-pixel combiner (sigma clipping, winsorised and linear fit) on made-up frames of the size asked for, on the CPU and on the GPU, and print the median times, the speed-up and how far the two results differ (as a fraction of the data range, and in pixels that have data in only one). One run warms each kernel up first, so the times are steady state. --adapter hardware (the default) uses a real GPU, software the fallback adapter (lavapipe, WARP) that CI uses; the software adapter is slower than the CPU code and exists to test the kernels. The same switch, --backend auto|cpu|gpu, is on calibrate, register and stack; auto uses a real GPU only for stack, where the frames stay on the device from the warp to the combine, because for one stage alone the copies across the bus cost more than the kernel saves.

valerian bench [OPTIONS]

Options:

• --adapter <ADAPTER>: The adapter to open (default hardware)
  • hardware: A real GPU
  • software: The software adapter (lavapipe, WARP)
• --width <PIXELS>: Frame width in pixels (default 4096)
• --height <PIXELS>: Frame height in pixels (default 3072)
• --frames <N>: Frames in the combine (3 to 128) (default 20)
• --repeats <N>: Timed repeats of each stage (the median is shown) (default 3)

valerian background

Fit a smooth surface to the sky of a stacked image and take it out. The image is cut into tiles, each gives the median of its clear pixels, and a polynomial or a thin-plate spline is fitted to those samples, rejecting samples that stars, nebulosity or the target lift above the sky. Stars are then masked from the residual and the fit is repeated. By default the surface is subtracted and the mean level is put back, so the gradient goes and the sky stays where it was. If too little clear sky is left (a target that fills the frame) the plane is reported as declined and left unchanged instead of subtracting the target. Colour planes are fitted one by one; raw mosaics must be demosaiced first.

valerian background [OPTIONS] --output <FILE> <INPUT>

Arguments:

• <INPUT>: The stacked FITS image (mono or colour planes, not a raw mosaic) (required)

Options:

• -o, --output <FILE>: The corrected FITS file to write (required)
• --save-model <FILE>: Also write the fitted background (one plane per input plane) to this FITS file
• --model <MODEL>: The surface to fit (default polynomial)
  • polynomial: A polynomial of --degree: degree 1 is a plane
  • spline: A thin-plate spline with --smoothing: follows any smooth gradient
• --degree <N>: Polynomial degree, 0 to 6 (default 2)
• --smoothing <S>: Spline smoothing: about 0.001 to 0.01 for a hundred tiles; larger tends to a plane (default 0.005)
• --mode <MODE>: Subtract the background or divide by it (default subtract)
  • subtract: Subtract: light pollution and other added light
  • divide: Divide: vignetting and other falloff
• --level <LEVEL>: Keep the mean level or remove the whole surface (default preserve)
  • preserve: Remove the gradient but keep the mean level
  • zero: Remove the whole surface: the sky goes to about zero (subtract) or one (divide)
• --tile <PX>: Tile size in pixels; default a thirty-second of the short side (at least 32) (default 0)
• --star-sigma <SIGMA>: Mask pixels this many robust sigmas above the surface as stars (default 3)
• --mask-grow <PX>: Grow the star mask by this many pixels (default 3)
• --clip-low <SIGMA>: Reject samples this many sigmas below the fit (default 3)
• --clip-high <SIGMA>: Reject samples this many sigmas above the fit (default 2)
• --rounds <N>: Rounds of mask refinement after the first fit (default 3)
• --exclude-target: Leave out the bright central target, sized from the data (for a large galaxy or nebula that fills much of the frame)

valerian stretch

Stretch a linear image. The black point is put just below the sky and the white point at a high percentile (or set both with --black and --white); the curve then bends the range onto 0 to 1: the midtone transfer function (the default, which puts the sky at --target), arcsinh, or the generalised hyperbolic stretch. The input is never changed. The output is a 32-bit float FITS file in 0 to 1, and its header records the stretch, so --invert can undo it on the data that was not clipped. --preview writes the result as a reduced PNG as well (or instead of the FITS file) to look at an automatic stretch before committing to it. Colour planes share one stretch unless --unlinked is given.

valerian stretch [OPTIONS] <INPUT>

Arguments:

• <INPUT>: The linear FITS image to stretch (required)

Options:

• -o, --output <FILE>: The stretched FITS file to write (optional with --preview)
• --preview <PNG>: Also write the stretched image as an 8-bit PNG, reduced to --preview-size
• --preview-size <PIXELS>: Longest side of the --preview PNG, in pixels (default 1600)
• --invert: Undo the stretch recorded in the input's header instead of stretching
• --curve <CURVE>: Tone curve (default auto)
  • auto: A midtone transfer function that puts the sky at --target
  • mtf: Midtone transfer function with the given --midtone (or solved for --target)
  • arcsinh: asinh(beta x) / asinh(beta), with --beta
  • ghs: Generalised hyperbolic stretch, with the --ghs-* parameters
• --target <LEVEL>: Sky level after the stretch, 0 to 1 (auto, and mtf without --midtone) (default 0.1)
• --midtone <M>: Midtone balance of the MTF, 0 to 1: below 0.5 brightens
• --beta <BETA>: Strength of the arcsinh stretch (default 50)
• --ghs-stretch <S>: GHS stretch factor: 0 changes nothing; D is e to this power minus one (default 3)
• --ghs-b <B>: GHS local intensity b: -1 logarithmic, 0 exponential, above 0 hyperbolic (default 0)
• --ghs-sp <SP>: GHS symmetry point, 0 to 1: the brightness that is stretched hardest (default 0)
• --ghs-lp <LP>: GHS shadow protection point (at most the symmetry point) (default 0)
• --ghs-hp <HP>: GHS highlight protection point (at least the symmetry point) (default 1)
• --black <ADU>: Black point, in the image's own units (with --white)
• --white <ADU>: White point, in the image's own units (with --black)
• --shadow-sigma <SIGMA>: Automatic black point: this many robust sigmas below the sky (default 2.8)
• --white-percentile <PERCENT>: Automatic white point: this percentile of the pixels (default 99.995)
• --unlinked: Stretch each colour plane on its own instead of all alike

valerian starless

Remove the stars from an image with a classical method and no learned model: stars are detected on the luminance, each gets a mask disc sized from its brightness and width, and the masked pixels of every plane are filled by diffusion (Laplace inpainting) from the pixels around them, with noise of the local level added so the patches do not show. The input is never changed. The starless image is written to -o; --stars-out writes what was taken out (original minus starless), which can be added back later; --mask-out writes the mask. --strength below 1 removes only that fraction of every star, reducing them. Work on the linear image or a stretched one; raw mosaics must be demosaiced first. It does not recreate texture a star hides, and diffraction spikes and stars below the detection limit stay.

valerian starless [OPTIONS] <INPUT>

Arguments:

• <INPUT>: The FITS image (mono or colour planes, not a raw mosaic) (required)

Options:

• -o, --output <FILE>: The starless FITS file to write (optional with --preview)
• --stars-out <FILE>: Also write what was removed (original minus starless) to this FITS file
• --mask-out <FILE>: Also write the star mask (1 where pixels were filled) to this FITS file
• --preview <PNG>: Also write a PNG of the original and the starless image side by side, both on the automatic stretch of the original and reduced to --preview-size
• --preview-size <PIXELS>: Longest side of each half of the --preview PNG, in pixels (default 900)
• --strength <FRACTION>: Fraction of each star to remove, 0 to 1: below 1 reduces stars instead (default 1)
• --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise: lower finds fainter stars (default 4)
• --mask-scale <FACTOR>: Multiplier of every mask radius (default 1)
• --grow <PIXELS>: Pixels added to every mask radius (default 1.5)
• --max-radius <PIXELS>: Largest mask radius in pixels (default 60)
• --no-noise: Fill with the smooth diffusion result and add no noise
• --seed <N>: Seed of the added noise (default 1)

valerian solve

Find where on the sky an image points and write the world coordinate system into a copy of it. Stars are detected, the catalogue stars of the patch of sky the header (or --ra and --dec) names are matched to them by triangle patterns, and a TAN projection with optional SIP distortion is fitted to every star that agrees. The position comes from the RA and DEC (or OBJCTRA and OBJCTDEC) keywords or an existing WCS, the pixel scale from FOCALLEN and XPIXSZ, and either can be given on the command line. With no position at all the whole sky is searched, which needs --scale or --scale-range and takes longer (--blind says so on purpose). The catalogue is Gaia DR3 to G = 11, found beside the program, in VALERIAN_CATALOGUE or with --catalogue; build a deeper one with scripts/build_catalogue.py for fields much narrower than half a degree. At least ten stars must agree or nothing is written. The input is never changed.

valerian solve [OPTIONS] <INPUT>

Arguments:

• <INPUT>: The FITS image (mono or colour planes, not a raw mosaic) (required)

Options:

• -o, --output <FILE>: Write a copy of the image with the WCS in its header (without it the solution is only printed)
• --catalogue <FILE>: The star catalogue (default: gaia-dr3-g11.vcat beside the program or in VALERIAN_CATALOGUE)
• --ra <RA>: Right ascension of the field centre: degrees, or hours as hh:mm:ss
• --dec <DEC>: Declination of the field centre: degrees, or dd:mm:ss
• --radius <DEGREES>: How far the true centre may be from the position, in degrees (default 1)
• --scale <ARCSEC>: Pixel scale in arc seconds per pixel (searched within 15 per cent either way)
• --scale-range <LOW> <HIGH>: Range of the pixel scale in arc seconds per pixel (repeatable)
• --blind: Search the whole sky even if the header names a position
• --sip-order <ORDER>: SIP distortion order, 0 for none, or auto to use it when it clearly helps (default auto)
• --min-matches <N>: The fewest stars that must agree (default 10)
• --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise (default 6)

valerian photocal

Set the white balance of a colour image from the stars in it. The stars of the plate solution (the image's own WCS, one from --wcs, or a quick solve from the header) are matched to Gaia stars with a BP-RP colour, each is measured through the same aperture in red, green and blue, and a line of instrumental colour against BP-RP is fitted for red and for blue against green with outlier rejection. The gains make a star of --reference-colour (0.82, the Sun) neutral; green is left alone so the brightness stays. The sky of the three planes is then brought to a common level so the background is neutral grey (--no-neutralise leaves it). The input must be a linear red, green, blue image (not stretched, not a raw mosaic) and the catalogue must carry colours (version 2); calibrate after background extraction and before stretching. The gains and offsets are written to the header as PCCGAINR, PCCGAING, PCCGAINB, PCCOFFR, PCCOFFG and PCCOFFB. Without -o the result is only printed. The input is never changed.

valerian photocal [OPTIONS] <INPUT>

Arguments:

• <INPUT>: The linear colour FITS image (three planes) (required)

Options:

• -o, --output <FILE>: Write the calibrated image here (without it the result is only printed)
• --wcs <FILE>: Take the plate solution from this FITS file's header instead of the image's
• --catalogue <FILE>: The star catalogue (default: gaia-dr3-g11.vcat beside the program or in VALERIAN_CATALOGUE)
• --stars-out <FILE>: Write every star measured (position, G, BP-RP, fluxes, used) to this CSV file
• --reference-colour <BP-RP>: The BP-RP colour to make neutral; 0.82 is a G2V star like the Sun (default 0.82)
• --min-mag <MAG>: Brightest star used, Gaia G magnitude (default 6)
• --max-mag <MAG>: Faintest star used, Gaia G magnitude (default 11)
• --colour-min <BP-RP>: Bluest BP-RP used in the fit (default 0.3)
• --colour-max <BP-RP>: Reddest BP-RP used in the fit (default 2.5)
• --aperture <FWHM>: Aperture radius as a multiple of the median FWHM (default 2)
• --min-snr <SNR>: Least signal-to-noise of a star in each colour (default 15)
• --min-stars <N>: The fewest stars the fit may rest on (default 15)
• --no-neutralise: Leave the background levels of the planes as they are

valerian info

Describe FITS files, or this build and the machine it runs on

valerian info [OPTIONS] [FILES]...

Arguments:

• <FILES>: FITS files to describe; with none, describe this build (repeatable)

Options:

• --stats: For each file, also measure the sky, noise and stars
• --gpu: Open the GPU adapter and report it
• --software: With --gpu, use the software (fallback) adapter instead of a real GPU