Skip to content

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 [OPTIONS] <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
  • deconvolve: Sharpen a stack with the stars' own point spread function (Richardson-Lucy)
  • solve: Plate-solve an image and write its world coordinate system (TAN-SIP)
  • photocal: Calibrate the colour of an image against Gaia star colours
  • subframes: Measure every frame and approve or reject it, with plots and a report
  • annotate: Draw the plate solution on an image: RA/Dec grid, catalogue objects, Gaia stars, residuals
  • photometry: Aperture photometry of one star across frames: a light curve with comparison stars
  • optics: Aberration inspector, FWHM and eccentricity maps, tilt hint and PSF profile of an image
  • plot: Draw one science plot (PNG, with its CSV and JSON beside it)
  • info: Describe FITS files, or this build and the machine it runs on

Options:

  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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. With --grade, raw Seestar S50 subs are scored by a neural-network grader first, and the ones below --min-grade (or over a --reject-defect limit) are left out with the reason printed; --grade-weights also multiplies each kept frame's weight by its score. Other frames are not graded. The frame limits (--max-fwhm, --max-ellipticity, --min-star-count, --max-noise, --min-snr-weight, --max-residual, --outlier-sigma) leave the frames they reject out of the stack: the frames are registered and judged, then registered and combined again without the rejected ones, and the names and reasons are printed. With --science-report the report still lists every frame.

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
  • --approve <FILE>: Leave out the frames this approve/reject table (CSV or JSON from valerian subframes) marks as rejected. Frames it does not name are kept
  • --grade: Optional, off by default: grade each raw Seestar S50 sub with the neural-network grader, before anything else. Other frames are left alone, with a note
  • --min-grade <SCORE>: With --grade: reject frames that score below this, 0 (unusable) to 1 (clean) (default 0.5)
  • --reject-defect <NAME:P>: With --grade: also reject frames whose chance of a defect is at or above P. NAME is cloud_haze, trail, blur or star_poor; the dew output is not reliable. Repeat for several (repeatable)
  • --grader-model <FILE>: With --grade: use this ONNX grader model instead of the built-in one
  • --grade-weights: With --grade: also multiply each kept frame's stack weight by its grade score, so cleaner frames count for more
  • --science-report <DIR>: Write the subframe analysis of this stack (plots, CSV, JSON, report.html) to this directory
  • --max-fwhm <PIXELS>: Reject frames with a larger FWHM, in pixels
  • --max-ellipticity <E>: Reject frames with a larger eccentricity (1 - b/a, 0 to 1)
  • --min-star-count <N>: Reject frames with fewer detected stars
  • --max-noise <ADU>: Reject frames with more noise, in ADU
  • --min-snr-weight <W>: Reject frames with a lower SNR weight (1 is the median frame)
  • --max-residual <PIXELS>: Reject frames with a larger registration residual, in pixels
  • --outlier-sigma <SIGMA>: Reject frames this many robust sigmas (1.4826 MAD) from the median in the bad direction of any measurement
  • --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
  • --memory <MIB>: Memory for the stack, in MiB. Frames are read one at a time, resampled into a staging file and combined a band of rows at a time, so the peak follows this and not the number of frames. Ignored with --science-report, which holds every frame (default 4096)
  • --scratch-dir <DIR>: Directory for the staging file (frames x width x height x planes x 4 bytes), used when the stack does not fit --memory; the system temporary directory by default. The file is removed when the run ends
  • --mosaic: Stack a mosaic: register every pane onto one larger canvas instead of keeping the reference frame's grid. Frames that do not overlap the reference are matched to the panes already placed. Seams are feathered (see --mosaic-feather) and --coverage shows how many frames reached each pixel. Not with --science-report
  • --mosaic-feather <PIXELS>: With --mosaic: width in pixels of the ramp at each frame's edge, over which its weight rises from nearly zero to full, so overlapping panes cross-fade. 0 gives hard edges (default 120)
  • --no-mosaic-level-match: With --mosaic: do not fit a level per frame from the overlaps; every frame keeps the sky level the usual normalisation gives it
  • --mosaic-min-coverage <FRAMES>: With --mosaic: keep only the part of the canvas that at least this many frames reach, and cut the canvas to it. Thin edges (a frame or two) are noisy; the Seestar's own mosaic keeps only the well-covered middle (default 1)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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
  • --science-report <DIR>: Write the integration diagnostics of this drizzle (weight, pixel-count and outlier-rejection maps, histograms; plots, CSV, JSON, report.html) to this directory
  • --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
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

valerian deconvolve

Sharpen a linear image by deconvolution. Stars are detected, the bright isolated ones are stamped, centred to a fraction of a pixel and combined into a point spread function (PSF) for each tile of the image, so the PSF follows the field's elongation and aberration from the middle to the corners. Each colour plane of each tile is then deconvolved by Richardson-Lucy iterations with total-variation damping (Dey et al. 2006) and the tiles are blended over their overlaps. Run it on the linear stack, after background if there is a gradient, and before stretch. More iterations are sharper and noisier; the default is a measured middle ground. A Gaussian PSF of a given FWHM can be set with --psf-fwhm when there are too few stars. The input is never changed; the report lists the PSF of every tile.

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

Arguments:

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

Options:

  • -o, --output <FILE>: The deconvolved FITS file to write (required)
  • --mode <MODE>: What the stars become: round (one round width everywhere) or full (the sharpest) (default round)
  • round: Round stars of one width everywhere: undoes the elongation and its variation over the field
  • full: Deconvolve by the whole measured PSF: the sharpest, keeps any elongation that survives
  • --target-fwhm <PIXELS>: Star FWHM in pixels that round aims for. Default: --target-ratio of the narrowest PSF axis of any tile
  • --target-ratio <RATIO>: The automatic round target as a share of the narrowest PSF axis, 0.3 to 1: lower is sharper and noisier (default 0.7)
  • --iterations <N>: Richardson-Lucy iterations, 1 to 200: more is sharper and noisier (default 20)
  • --tv <LAMBDA>: Total-variation damping, 0 to 1 (0 is plain Richardson-Lucy): higher keeps the noise smoother (default 0.002)
  • --roundness <SHARE>: How far round evens out the stars' elongation before it sharpens, 0 to 1: 1 gives the roundest stars, 0 the sharpest (default 0.5)
  • --saturation <LEVEL>: Pixel value at which stars are clipped: auto (found from the image), off, or a number in the image's units (default auto)
  • --ring-guard <STRENGTH>: Strength of the guard that stops a dark ring forming around bright stars, 0 to 1 (0 is off) (default 1)
  • --psf-fwhm <PIXELS>: Use a round Gaussian PSF of this FWHM in pixels everywhere instead of measuring one from the stars
  • --tiles <AxB>: Tiles across and down, as ACROSSxDOWN (for example 3x4); the default cuts tiles of about 480 pixels
  • --psf-radius <PIXELS>: Half-width of the PSF kernel in pixels, 3 to 24 (default 10)
  • --psf-stars <N>: Most stars used for the PSF of one tile (default 40)
  • --min-psf-stars <N>: Fewest stars a tile's PSF may be measured from; a tile with fewer widens its search (default 8)
  • --psf-min-snr <SNR>: Faintest star used for a PSF, as peak over pixel noise (default 25)
  • --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise (default 5)
  • --report <FILE>: Also write the PSF of every tile (position, stars, FWHM, ellipticity) to this CSV file
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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
  • --report <DIR>: Write the colour-calibration scatter (instrumental colour against Gaia BP-RP, with the fitted lines), the zero points and colour terms, the limiting magnitude and the calibrated star catalogue (PNG, CSV, JSON, report.html) to this directory
  • --calibrated-stars <FILE>: Write the calibrated star catalogue (every detected star with Gaia-G equivalent magnitudes and errors in red, green and blue) to this CSV file
  • --limit-snr <SNR>: The signal-to-noise ratio that defines the limiting magnitude (default 5)
  • --field-threshold <SIGMA>: Detection threshold of the catalogue stars, in sigmas of the smoothed noise (default 5)
  • --max-field-stars <N>: The most stars measured for the catalogue (the brightest) (default 5000)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

valerian subframes

Subframe analysis in the manner of PixInsight's SubframeSelector. The frames are registered to the sharpest and each is measured: stars, FWHM, eccentricity, sky background, noise, an SNR weight (relative to the median, from the noise and the transparency) and the registration residual. Frames are approved or rejected against the limits given (a frame that does not register is always rejected). --report writes subframes.csv and subframes.json (the approve/reject table, with the reason for each rejection), plots of every quantity against frame number and against time as PNG, and report.html, which holds them all and can be opened or mailed on its own. Edit the approved column of the CSV by hand if you disagree, then give it to valerian stack --approve so the stack uses what you approved. With --grade, raw Seestar S50 subs are also scored by a small neural-network grader (0 unusable to 1 clean, with the chance of cloud or haze, trail, blur and too few stars, and a dew chance that is not reliable); the scores join the table and frames below --min-grade, or over a --reject-defect NAME:P limit, are rejected. The grader is trained on Seestar S50 subs only; other frames are skipped with a note. The input is never changed.

valerian subframes [OPTIONS] <FRAMES>...

Arguments:

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

Options:

  • --report <DIR>: Directory for the plots, CSV, JSON and report.html (default subframes-report)
  • --max-fwhm <PIXELS>: Reject frames with a larger FWHM, in pixels
  • --max-ellipticity <E>: Reject frames with a larger eccentricity (1 - b/a, 0 to 1)
  • --min-star-count <N>: Reject frames with fewer detected stars
  • --max-noise <ADU>: Reject frames with more noise, in ADU
  • --min-snr-weight <W>: Reject frames with a lower SNR weight (1 is the median frame)
  • --max-residual <PIXELS>: Reject frames with a larger registration residual, in pixels
  • --outlier-sigma <SIGMA>: Reject frames this many robust sigmas (1.4826 MAD) from the median in the bad direction of any measurement
  • --reference <N>: Index (from 0, in sorted order) of the reference frame; default the sharpest
  • --grade: Optional, off by default: grade each raw Seestar S50 sub with the neural-network grader, before anything else. Other frames are left alone, with a note
  • --min-grade <SCORE>: With --grade: reject frames that score below this, 0 (unusable) to 1 (clean) (default 0.5)
  • --reject-defect <NAME:P>: With --grade: also reject frames whose chance of a defect is at or above P. NAME is cloud_haze, trail, blur or star_poor; the dew output is not reliable. Repeat for several (repeatable)
  • --grader-model <FILE>: With --grade: use this ONNX grader model instead of the built-in one
  • --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
  • --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)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

valerian annotate

Draw a plate solution on its image. The image's own world coordinate system is used (written by valerian solve), or the one in --wcs, or one found by a quick solve from the header's position and scale. The picture is the automatically stretched image, reduced to --max-side pixels, with an RA/Dec grid whose spacing is chosen for the field and labelled at the edges, the objects of the bundled NGC, IC and Messier list that lie in the field (an ellipse of the catalogued size and angle, named), and the Gaia stars brighter than --star-mag (labelled with their magnitude when brighter than --label-mag). Each layer can be left out. The residuals of the solution are also drawn: every detected star that matches a Gaia star within 3 pixels gives a vector (detected minus where the solution puts the catalogue star), shown over the frame with exaggerated arrows and against magnitude, with the rms in pixels and arc seconds. --report writes annotated.png, annotated_objects.csv, annotated_stars.csv, wcs_residuals.png and .csv, astrometry.json and report.html. The bundled object list is a subset of OpenNGC (CC BY-SA 4.0). The input is never changed.

valerian annotate [OPTIONS] <IMAGE>

Arguments:

  • <IMAGE>: The solved FITS image (linear or stretched) (required)

Options:

  • --report <DIR>: Directory for the picture, lists, residuals and report.html (default astrometry-report)
  • --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)
  • --no-grid: Leave the RA/Dec grid out
  • --no-objects: Leave the catalogue objects out
  • --no-stars: Leave the Gaia stars out
  • --star-mag <MAG>: Faintest Gaia star drawn, G magnitude (default 10)
  • --label-mag <MAG>: Gaia stars brighter than this, G magnitude, are labelled (default 8)
  • --max-side <PIXELS>: Longest side of the picture in pixels (default 1400)
  • --map-grid <N>: Cells per side of the astrometric residual map (2 to 24) (default 6)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

valerian photometry

Measure one star in every frame. The frames are registered to the sharpest, the star's position in the reference frame (--star X,Y, or the brightest unsaturated star) is carried to every frame through the registration and refined by a centroid, and its flux is the sum of the pixels in a circle of --aperture times the reference FWHM (with the pixels cut by the edge counted by their fraction) less the clipped median of a sky annulus. Up to --comparison bright, isolated, unsaturated stars of the reference frame are measured the same way; their summed flux is the ensemble, and the star's magnitude against it, minus its median, is the relative magnitude, with an error from the sky noise. The first comparison star is measured against the others as a check star, which should stay flat. --report writes lightcurve.png, lightcurve.csv (time, position, flux, sky, S/N, magnitudes, error, flag per frame), lightcurve.json and report.html. Frames without DATE-OBS are plotted by number.

valerian photometry [OPTIONS] <FRAMES>...

Arguments:

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

Options:

  • --report <DIR>: Directory for the light curve, its data and report.html (default photometry-report)
  • --star <X,Y>: The star as X,Y pixels in the reference frame (default: the brightest unsaturated star)
  • --aperture <FWHM>: Aperture radius as a multiple of the reference frame's FWHM (default 2)
  • --comparison <N>: Comparison stars to use at most (default 10)
  • --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
  • --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)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

valerian optics

What the stars of one image say about the telescope. The stars are detected on the luminance and measured (FWHM, eccentricity, orientation); those that are not saturated and have a peak of at least --min-snr times the noise are kept (at least 30 are needed). --report writes: aberration_inspector.png, a 3 by 3 mosaic of crops at the corners, edges and centre, stretched alike, each labelled with the median FWHM and eccentricity of the stars around it; fwhm_map.png and eccentricity_map.png, a polynomial surface of degree --order fitted to the stars with 3-sigma rejection and drawn as an interpolated image with contours and the stars on it (whiskers on the eccentricity map show which way the stars are elongated); tilt.png and a hint in words from the FWHM of the centre and the four corners (curvature, tilt, the softest corner, and whether the outer stars are elongated along or across the radius); and psf.png, the stacked radial profile of the brightest isolated stars with a Moffat and a Gaussian fit. Every plot has its data beside it as CSV or JSON (optics.json holds the tilt, the panels and the fit) and report.html gathers them. The hint says what the pattern is consistent with; it cannot tell which way to move a spacer from one image. The input is never changed.

valerian optics [OPTIONS] <IMAGE>

Arguments:

  • <IMAGE>: The FITS image (a single frame or a stack; colour images use the luminance) (required)

Options:

  • --report <DIR>: Directory for the plots, CSV, JSON and report.html (default optics-report)
  • --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise (default 5)
  • --min-snr <RATIO>: The smallest peak-to-noise ratio of a star that is measured (default 10)
  • --crop <PIXELS>: Aberration inspector: side of a crop in pixels (32 to 512, even) (default 128)
  • --zoom <FACTOR>: Aberration inspector: enlargement of a crop (1 to 6) (default 2)
  • --order <DEGREE>: Maps: degree of the polynomial surface fitted to the stars (1 to 4) (default 3)
  • --psf-stars <N>: PSF profile: how many of the brightest isolated stars to stack (default 50)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

valerian plot

Draw one of the science plots on its own. KIND is subframes: the per-frame plots of valerian subframes, from frames (they are measured first) or from a subframes.json written earlier. The PNG is written to -o, with a CSV and a JSON of the plotted data beside it. --x chooses frame number or time on the horizontal axis. Use --report of the producing command for a whole session at once.

valerian plot [OPTIONS] --output <FILE> <KIND> <INPUT>...

Arguments:

  • <KIND>: Which plot (required)
  • subframes: Per-frame FWHM, eccentricity, star count, background, noise, SNR weight and registration residual
  • aberration: The aberration inspector: crops at the corners, edges and centre (an image)
  • fwhm-map: The FWHM map across the field (an image)
  • eccentricity-map: The eccentricity map across the field, with whiskers (an image)
  • tilt: The FWHM of the centre and the four corners (an image)
  • psf: The stacked radial profile with a Moffat fit (an image)
  • rejection-low: Samples rejected below the centre, per pixel (frames, stacked on the CPU)
  • rejection-high: Samples rejected above the centre, per pixel (frames, stacked on the CPU)
  • weight-map: Summed weight of the samples used, per pixel (frames, stacked on the CPU)
  • count-map: Samples used, per pixel (frames, stacked on the CPU)
  • noise: Noise against the number of frames stacked, with the square-root law (frames)
  • histogram: Histogram of each channel, linear and stretched (an image)
  • annotate: The plate solution drawn on the image: grid, objects, Gaia stars (a solved image)
  • residuals: Residual vectors of the plate solution (a solved image)
  • pcc: Photometric colour calibration scatter against Gaia BP-RP (a solved colour image)
  • lightcurve: Light curve of one star across frames (frames, with --star)
  • zeropoint: Zero point and colour term of each colour plane against Gaia (a solved colour image)
  • limiting-mag: Limiting magnitude: signal-to-noise and star counts against magnitude (a solved colour image)
  • residual-map: Astrometric residual map: mean residual per cell, radial and tangential terms (a solved image)
  • <INPUT>: Frames (FITS files or directories of them) to measure or stack, or one subframes.json written by valerian subframes; for the optics and histogram plots, one FITS image (required; repeatable)

Options:

  • -o, --output <FILE>: The PNG to write; the CSV and JSON of the plotted data go beside it (required)
  • --x <X>: Horizontal axis (default index)
  • index: Frame number
  • time: Hours since the first frame (needs DATE-OBS in every frame)
  • --max-fwhm <PIXELS>: Reject frames with a larger FWHM, in pixels
  • --max-ellipticity <E>: Reject frames with a larger eccentricity (1 - b/a, 0 to 1)
  • --min-star-count <N>: Reject frames with fewer detected stars
  • --max-noise <ADU>: Reject frames with more noise, in ADU
  • --min-snr-weight <W>: Reject frames with a lower SNR weight (1 is the median frame)
  • --max-residual <PIXELS>: Reject frames with a larger registration residual, in pixels
  • --outlier-sigma <SIGMA>: Reject frames this many robust sigmas (1.4826 MAD) from the median in the bad direction of any measurement
  • --threshold <SIGMA>: Detection threshold in sigmas of the smoothed noise, when frames or stars are measured (default 5)
  • --min-snr <RATIO>: Optics plots: the smallest peak-to-noise ratio of a star that is measured (default 10)
  • --crop <PIXELS>: Aberration inspector: side of a crop in pixels (32 to 512, even) (default 128)
  • --zoom <FACTOR>: Aberration inspector: enlargement of a crop (1 to 6) (default 2)
  • --order <DEGREE>: Maps: degree of the polynomial surface fitted to the stars (1 to 4) (default 3)
  • --psf-stars <N>: PSF profile: how many of the brightest isolated stars to stack (default 50)
  • --wcs <FILE>: Annotate, residuals and pcc: take the plate solution from this FITS file's header
  • --catalogue <FILE>: Annotate, residuals and pcc: the star catalogue (default: the one beside the program)
  • --star-mag <MAG>: Annotate: faintest Gaia star drawn, G magnitude (default 10)
  • --star <X,Y>: Lightcurve: the star as X,Y pixels in the reference frame (default: the brightest unsaturated star)
  • --aperture <FWHM>: Lightcurve: aperture radius as a multiple of the reference FWHM (default 2)
  • --comparison <N>: Lightcurve: comparison stars to use at most (default 10)
  • --limit-snr <SNR>: Zeropoint and limiting-mag: the signal-to-noise ratio that defines the limit (default 5)
  • --grid <N>: Residual-map: cells per side of the grid (2 to 24) (default 6)
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written

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
  • --keep-location: Keep the observing site (SITELAT, SITELONG, OBSGEO-* ...), device serial numbers and unit identifiers (the hex part of a Seestar's TELESCOP) in the headers of files written. By default they are dropped from everything written