Command line reference¶

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

helia¶

Solar lucky-imaging stacker

helia [OPTIONS] <COMMAND>

Subcommands:

• stack: Stack a capture into a single sharp image
• calibrate: Build master dark, flat and bad-pixel files from calibration captures, for helia stack --dark --flat --bad-pixels
• edit: Sharpen and adjust an existing TIFF, PNG or FITS image
• info: Print what a capture file contains: every header field as written, what Helia will use instead where it differs, and why
• measure: Measure how much granulation an image holds: the band-pass contrast (standard deviation over mean) of a disc-centre crop in three bands, for comparing settings on the same capture
• sunspots: Find the sunspots on a stacked white-light image: groups, the relative Wolf number and areas corrected for foreshortening, as a table, JSON and an overlay picture
• timelapse: Make a time-lapse: stack each capture with the same settings, register the stacks to each other (limb fit and phase correlation of the disc centre), optionally even out the brightness, and write a numbered PNG or TIFF sequence and a movie (MP4 through ffmpeg, else an animated PNG)
• solar-derotate: Bring images of the Sun to one time by its differential rotation (Howard or Snodgrass rates, P, B0 and L0 from the capture times), so that features line up across a long session or between panels taken minutes apart
• derotate: Turn stacked images of one target to the same orientation, undoing the field rotation of an altazimuth mount between captures (a time-lapse)
• mosaic: Join panels of the Sun into a full-disc mosaic: match the overlaps (shift and a few degrees of turn), place all the panels at once by least squares, match their brightness, join along seams of least difference and feather the seams. The panels can be derotated to one time first
• plot: Draw one science figure again from a report directory that helia stack --report wrote (or stack a capture and draw it)
• serve: Run the HTTP/JSON API server
• presets: List the filter presets (helia stack --preset ...)
• lut: Write a filter's colour table as a file other programs read (.cube, .csv, ImageJ .lut or a PNG strip), so a picture coloured elsewhere matches one coloured by Helia
• feedback: Send feedback (a bug, a feature request or a question). It is sent to the Helia developers and filed in the Helia issue tracker, through the feedback service
• plugins: List, inspect, approve, set up and test plugins: programs that add a processing step or do the stacking elsewhere. Nothing runs until you enable it
• update: Check for a newer Helia, download it and install it, or go back to the previous version. Contacts the update server only when you run it
• tools: Install, check and remove optional programs such as ffmpeg. Nothing is installed without your say-so: the provider's full licence is shown and you must type yes before anything is downloaded

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia stack¶

Stack a capture into a single sharp image

helia stack [OPTIONS] --output <OUTPUT> <INPUT>

Arguments:

• <INPUT>: Capture file: .ser or .avi, or a compressed video (.mp4, .mov, .mkv, .webm, .m4v) read through the optional ffmpeg program, or FITS frames: a .fit, .fits or .fts file (a cube, or several images in one file), a folder of them, or a pattern such as 'Light_*.fit' (in quotes). The frames of a folder or pattern are stacked in DATE-OBS order, else file name order, and must all be the same size (required)

Options:

• -o, --output <OUTPUT>: Output image; the extension picks the format (.tif/.tiff, .png or .fits/.fit/.fts) (required)
• --keep <KEEP>: Share of frames to keep, e.g. 25%
• --keep-frames <N>: Number of frames to keep
• --ap-size <AP_SIZE>: Alignment point size in pixels. Default: chosen from the image size
• --ap-auto: Choose the alignment point size, spacing and search range from the image scale (the fitted limb) and the seeing (a probe of a dozen frames), instead of one size for every capture. What was chosen is printed
• --ap-passes <N>: Alignment point passes: 1 measures the points against the reference built from the best few frames, 2 stacks once and measures them again against that stack (less noise, more detail to lock on). Needs multipoint. Default: 1
• --ap-smooth <on|off>: Replace alignment point shifts that disagree with their neighbours (a mismatch on a neighbouring granule) by the neighbours' median. Needs multipoint. Default: off
• on: Enabled
• off: Disabled
• --ap-residual: Measure the alignment points once more against the finished stack and print how far the shifts that were used are from that (px RMS): a check of the registration, at the cost of one more measuring pass
• --autocrop: Crop the result to the solar disc plus a margin (FITS too). A capture without a clear disc is left as it is, with a note
• --seeing: Estimate the seeing from the capture: the Fried parameter r0 from the spectral ratio of tiles of the disc over a sample of all the frames (needs --aperture-mm), and a relative index from how much neighbouring alignment points move against each other. Printed after the stack and written into the FITS header. Reads about 120 more frames
• --report <DIR>: Write the science outputs of the stack into this directory (created): the frame quality graphs sorted and in capture order with the keep threshold, the quality histogram, the global shift and drift, the seeing over the capture, the alignment point plots, the power spectrum, transfer curves, limb profile and blur, histograms and noise, and the Stonyhurst and Carrington grids (with --sunspots, the sunspot table too), each as a PNG with its numbers as CSV and JSON, and report.html, one self-contained page with the figures, tables and the settings used. Turns the seeing probe on (about 120 more frames are read). Redraw one figure with helia plot
• --field-rotation: Undo the field rotation of an altazimuth mount: every frame is turned to the orientation of the middle of the capture (or --field-rotation-reference) from the parallactic angle of the Sun at the frame's SER timestamp, for the site given by --site or HELIA_SITE, before it is scored, aligned or stacked. Needs a capture with timestamps (SER, or FITS with DATE-OBS); not for an equatorial mount. FITS subs from an altazimuth mount that name their target, site and mount in the header (a Seestar's do) need no flag: the correction is made by itself, about their target and site; stop it with --no-field-rotation. Works with --colour true
• --no-field-rotation: Do not undo field rotation, even where the headers of FITS subs from an altazimuth mount (RA, DEC, SITELAT, SITELONG, EQMODE 0, DATE-OBS) would have it done by itself
• --field-rotation-reference <WHICH>: The orientation --field-rotation turns every frame to: middle (the default), first or last (default middle)
• --field-rotation-mirror: The picture is a mirror image (an odd number of reflections, a star diagonal for one): --field-rotation then turns the other way
• --sunspots: Find the sunspots on the stack: groups, the relative Wolf number, areas corrected for foreshortening. Printed after the stack, written into the FITS header, and saved beside the output as NAME-sunspots.csv, .json and .png. For a white-light capture with the whole disc in view; the time is the capture's
• --date <TIME>: When the capture was taken, UTC (YYYY-MM-DDThh:mm:ss), for a capture that does not hold its own time (an AVI or a video; a SER's time stamps are used otherwise). Gives P, B0 and L0 to --sunspots and to the heliographic grids of --report
• --sunspot-umbra <SHARE>: Umbra threshold: pixels darker than this share of the quiet disc (after the limb darkening is flattened out) are umbra (default 0.55)
• --sunspot-penumbra <SHARE>: Penumbra threshold: pixels darker than this share of the quiet disc are spot. Raise it to take in fainter penumbrae and pores (default 0.88)
• --sunspot-min-area <MSH>: Smallest spot to keep, in millionths of the visible hemisphere (default 2)
• --sunspot-max-area <MSH>: Largest spot, in millionths of the hemisphere; a dark region bigger than this (a cloud, a vignette) is left out (default 6000)
• --sunspot-group-gap <DEG>: Spots whose edges are closer than this on the Sun, in degrees, form one group (default 3)
• --wolf-k <K>: Observer factor k of the Wolf number R = k (10 g + s) (default 1)
• --north-angle <DEG>: How far solar north is turned counter-clockwise from the top of the image, in degrees. Default 0: solar north up (default 0)
• --celestial-north-up: The image has celestial north up (an equatorial mount): solar north is then turned by the position angle P of the Sun at the capture time, added to --north-angle
• --mirror: The image is a mirror image (west is on the left)
• --wavelength-nm <NM>: Wavelength in nanometres for --seeing and --report when the filter is not known (the filter's own wavelength is used otherwise)
• --aperture-mm <MM>: Telescope aperture in millimetres. With it, the granulation report of a white-light or sodium stack also gives the diffraction cut-off and how much of it the data resolves, and --seeing gives r0 and a grade
• --autocrop-margin <PERCENT>: Margin of --autocrop as a percentage of the disc radius (default 10)
• --preset <FILTER>: The filter the capture was taken with (ha, cak, cah, mg, na, he-d3, hbeta, white): applies its recommended channel and frame share and colours a .tif or .png output. Without it the filter is read from the file name, folder or sidecar when possible; see helia presets
• --colour <COLOUR>: Colour of the output: auto (the preset), mono, a preset id, or true (true colour from a raw colour camera: red, green and blue stacked on one alignment, channels aligned and white balanced, written as an RGB TIFF or PNG or a three-plane FITS). The other looks colour a .tif or .png from the mono stack; FITS output is mono for them
• --invert: Invert the picture before colouring (shows filaments and prominences)
• --white-balance <BALANCE>: White balance of --colour true: auto (make the disc centre neutral), off (the sensor's own balance) or three gains R,G,B such as 1.9,1,1.5 (default auto)
• --no-channel-align: With --colour true, do not register red and blue to green (atmospheric dispersion). On by default
• --colour-strength <S>: Mix of colour and grey from 0 to 1 (default 1)
• --grade <GRADE|PRESET>: Grade the colour: hue=DEG,sat=S,gamma=G,black=B,white=W,r=R,g=G,b=B (any of them; hue -180 to 180, sat 0 to 2, gamma 0.3 to 3, black 0 to 0.9, white 0.1 to 1, r/g/b channel curves 0.3 to 3; the default changes nothing), or the name of a saved colour preset (a file in the colour presets folder, or a .json file)
• --site <LAT,LON,ALT>: Observing site as LAT,LON,ALT (degrees north, degrees east, metres), for a FITS output's OBSGEO-X/Y/Z. Without it the HELIA_SITE environment variable is used, else the keywords are left out
• --align <ALIGN>: How whole frames are aligned: auto (fit the solar limb when the full disc is in view and the fit is confident, else phase correlation), phase (phase correlation, best for a cropped region) or limb (fit the limb; frames without a usable limb still use phase correlation) (default auto)
• --sharpen-fits: Apply the sharpening and other edits to FITS output too. By default a FITS file is the unsharpened stack, for further processing elsewhere
• --sharpen <METHOD>: Sharpening: wavelet (Registax-style layers, the usual choice), unsharp, rl (Richardson-Lucy deconvolution) or none. The default is none
• --unsharp-radius <PX>: Unsharp mask: Gaussian radius (sigma) in pixels
• --unsharp-amount <A>: Unsharp mask: how much detail is added back (0.6 is gentle, 2 is strong)
• --unsharp-threshold <T>: Unsharp mask: detail weaker than this (0 to 1) is left alone, so noise is not boosted
• --wavelets <SPEC>: Wavelets as in RegiStax 6: registax:l1=AMOUNT/SHARPEN/DENOISE,l2=..., scheme=dyadic|linear,filter=default|gaussian,initial=N,step=X,linked=on. AMOUNT is the layer slider (0 to 200 %), SHARPEN 0 to 1 (gain is 1 + AMOUNT x SHARPEN, so 100 and 0.14 is 15x), DENOISE 0 to 1.5 (a noise cut of 10 x DENOISE sigmas). Layers not named are left alone. Implies --sharpen wavelet; with --sharpen rl the wavelets run after the deconvolution (deconvolve first, then lift and denoise)
• --wavelet-gains <G1,G2,...>: Wavelets: gain of layers 1, 2, 3 ... (comma separated; 1 leaves a layer alone, above 1 sharpens it). Layers not listed keep the recommended gain
• --wavelet-noise <T1,T2,...>: Wavelets: noise threshold of layers 1, 2, 3 ... in noise sigmas (0 keeps all detail; 2 removes what is not clearly above the noise)
• --rl-iterations <N>: Richardson-Lucy: iterations (more is sharper and noisier)
• --rl-tv <L>: Richardson-Lucy: total-variation weight, 0 to 0.05 (keeps noise from becoming speckle)
• --rl-psf <PSF>: Richardson-Lucy: the blur to undo. auto (from the image scale), limb (measured from the solar limb: best for white light and calcium), gaussian:SIGMA, airy:RADIUS (first dark ring, pixels) or airy-scope:NM,MM,ARCSEC_PER_PX
• --rl-guard <S>: Richardson-Lucy: strength of the limb and sunspot ringing guard, 0 (off) to 1
• --flatten <SOURCE>: Divide the disc by its limb-darkening profile before anything else, so sharpening sees flat contrast: model (the fitted law) or profile (the measured azimuthal median). Outside the limb nothing changes
• --limb-law <LAW>: The limb-darkening law to fit: linear, quadratic (the default) or neckel (Neckel and Labs, five terms). helia stack prints the fit
• --prominence: Composite a stretched prominence layer with the disc: outside the fitted limb the scattered light is taken off and what is left is stretched to read like the disc, joined to it by a feathered edge. For H-alpha and the other lines with prominences. Runs after the sharpening
• --prominence-strength <S>: How hard the prominence layer is lifted: 1 refers it to the brightest prominence found
• --prominence-stretch <K>: The k of the asinh stretch of the layer; 0 is linear, larger lifts the faint parts more (default 6)
• --prominence-level <SHARE>: Brightness of the brightest prominence as a share of the disc's (default 0.75)
• --prominence-feather <SHARE>: Half-width of the feathered join at the limb, as a share of the disc radius (default 0.012)
• --prominence-reach <RADII>: How far out the layer reaches, in disc radii (default 1.4)
• --prominence-gate <SIGMA>: Noise sigmas taken off the layer before the stretch (default 3)
• --prominence-offset <SHARE>: Move the join of layer and disc, as a share of the disc radius added to the fitted limb (negative inside the limb, default 0)
• --prominence-disc-gamma <G>: Gamma of the disc's tone above the sky while the layer is on (default 1: the disc is left alone)
• --prominence-layer-gamma <G>: Gamma of the stretched layer's tone (default 1; above 1 darkens its faint parts)
• --denoise <STRENGTH>: Wavelet denoise; the strength is in noise sigmas for the finest layer (default: the filter's recommended value)
• --denoise-layers <N>: Layers the denoise treats, from the finest
• --black <V>: Levels: input value (0 to 1) that becomes black
• --white <V>: Levels: input value (0 to 1) that becomes white
• --gamma <G>: Levels: mid-tone gamma (above 1 brightens)
• --curve <IN:OUT,...>: A tone curve through IN:OUT points, for example 0.25:0.15,0.75:0.85
• --crop <X,Y,W,H>: Crop to X,Y,W,H in pixels (top-left origin)
• --rotate <DEG>: Rotate clockwise by this many degrees (multiples of 90 are exact)
• --flip-h: Mirror left to right
• --flip-v: Mirror top to bottom. An edit on the finished picture, applied after the capture is read; to correct how FITS frames are read use --row-order
• --resize <SIZE>: Resize: 50% or 0.5, 1200x800, 1200x (width) or x800 (height)
• --edits <NAME|FILE>: Start from a saved edit preset (a name from the presets folder, or a .json file); the options above are added after it
• --save-edits <NAME>: Save the resulting edit list as a preset under this name, for --edits
• --no-multipoint: Skip multi-point alignment (global alignment only)
• --exclude <X,Y,W,H>: Keep alignment and quality scoring off this rectangle, given as x,y,w,h in pixels (top-left origin); repeat for several. The area is filled in every frame from the sky around it, so no patch shows in the result. Burned-in timestamps are found automatically; use this for anything else (a logo, a hot pixel cluster) (repeatable)
• --prominence-band <PX>: Place alignment points up to this many pixels outside the fitted limb, so they can follow prominences (0 keeps them on the disc) (default 0)
• --no-disc-mask: Do not fit the limb; alignment points may sit anywhere there is contrast
• --no-overlay-detect: Do not look for burned-in text (a capture timestamp) to mask
• --backend <BACKEND>: Compute backend (default auto)
• --dark <PATH>: Master dark (FITS from helia calibrate, or any FITS or TIFF), or dark captures to build one from (a SER, AVI or FITS file, or a folder). Subtracted from every frame before it is demosaiced or aligned
• --flat <PATH>: Master flat, or flat captures to build one from. Divided out of every frame after the dark
• --displaced <PATH>: Captures of the Sun at many places on the sensor, to solve a flat from (see helia calibrate --displaced); used when no --flat is given. The dark is taken off first
• --displaced-keep-smooth: With --displaced, keep every scale of the solution (see helia calibrate --displaced-keep-smooth)
• --flat-dark <PATH>: Dark captures at the exposure of the flats, when --flat is captures
• --bias <PATH>: Master bias (or captures). Only used with --scale-dark
• --bad-pixels <FILE>: Bad-pixel map: bad-pixels.fits from helia calibrate, or a text file with an x y pair (from 0, top-left) per line. Without it, hot pixels of the dark and dead pixels of the flat are found and corrected
• --no-cosmetic: Do not look for hot and cold pixels in the dark and the flat
• --scale-dark: Scale the dark by the ratio of the exposures (the Sun's exposure comes from the SharpCap sidecar). Best with --bias
• --calibration-combine <CALIBRATION_COMBINE>: How frames are combined into a master: median, sigma or sigma:K (default sigma)
• --sigma-clip <K>: Enable sigma clipping at this many standard deviations (off by default). Same as --robust sigma --robust-k K
• --robust <ROBUST>: Outlier-robust combination of the frames at each pixel: sigma drops outliers, huber down-weights them, winsor clamps them. Two passes over the frames. Default none, the weighted mean. Removes what differs between frames (a satellite, a cosmic ray, a hot pixel that the alignment moves); a defect fixed on the sensor is in the same place in every frame and needs --dark or --bad-pixels instead
• none: Weighted mean of every sample (the default)
• sigma: Drop samples further than K sigma from the mean (default K 2.5)
• huber: Huber M-estimator: down-weight samples beyond K sigma in proportion to their distance (default K 1.345)
• winsor: Winsorised mean: clamp samples to K sigma from the mean (default K 2)
• --robust-k <K>: Threshold of --robust in standard deviations. Default: 2.5 for sigma, 1.345 for huber, 2 for winsor
• --bayer <BAYER>: Bayer handling: auto, none, rggb, bggr, grbg or gbrg. auto trusts the header, but for a SER file labelled mono it also checks the pixels for a hidden Bayer mosaic (some recorders label raw colour data as mono) and debayers when it finds one. none treats the frames as mono whatever the header or sidecar say; a pattern forces it. For AVI the pattern otherwise comes from the SharpCap sidecar. For FITS frames auto takes BAYERPAT (as stored) and ROWORDER from the header (default auto)
• --bit-depth <BITS>: Bits per sample, instead of the SER header's: 1 to 8 read one byte per pixel, 9 to 16 two bytes. For a header that gets the depth wrong. SER only
• --endian <ORDER>: Byte order of 16-bit samples, instead of the SER header flag (little or big). SER only
• --flip-rows: Read the rows bottom to top, for a file stored upside down. Patterns given to --bayer describe the picture after the flip. SER only
• --row-order <ORDER>: Which way up the rows of FITS frames are stored: auto, top-down or bottom-up. auto follows a ROWORDER card (TOP-DOWN or BOTTOM-UP) when there is one; without it Seestar S50 frames (INSTRUME or TELESCOP names an S50) are top-down and everything else is bottom-up, as the FITS standard says. top-down and bottom-up override the header. --flip-v is a separate edit applied to the result. FITS only (default auto)
• --channel <CHANNEL>: Colour channel to stack from a Bayer capture. Default: the preset's channel, else lum
• r: Red plane only (usual for H-alpha)
• g: Green plane only
• b: Blue plane only
• lum: Mean of the three planes
• --debayer <DEBAYER>: Demosaicing method (default mhc)
• bilinear: Plain bilinear interpolation
• mhc: Malvar-He-Cutler, edge aware
• --metric <METRIC>: Sharpness metric used to rank frames (default gradient)
• gradient: Gradient energy
• laplacian: Laplacian variance
• helmli: Helmli and Scherer's mean (CPU only)
• mfgs: Median-filter gradient similarity (CPU only)
• dct: DCT energy ratio (CPU only)
• fourier: Band-limited Fourier power less a noise floor (CPU only)
• contrast: Mean local RMS contrast (CPU only)
• --cache-dir <DIR>: Directory for compressed video (.mp4, .mov, .mkv, .webm, compressed .avi) decoded by ffmpeg. The decoded frames are uncompressed, so this needs room for the whole video (checked first) and is cleaned up afterwards. Default: the operating system's cache directory, or the HELIA_CACHE_DIR environment variable
• --plugin-step <SPEC>: Run a step of a plugin: PLUGIN/STEP, optionally followed by :KEY=VALUE,KEY=VALUE or :{"json":"object"} for its parameters. Repeat for several steps, which run in the order given. A frame-op step runs on every frame before stacking (stack only); an image-op step runs on the stack after Helia's own sharpening and edits, or before them when written pre:PLUGIN/STEP; an analyse step reads the result and writes OUTPUT.analysis.json. The plugin must be enabled first (helia plugins enable) (repeatable)
• --stack-backend <PLUGIN>: Stack with this stack-backend plugin instead of on this computer (stack only). The plugin gets the capture and the stacking settings; sharpening, colour and export stay in Helia. True colour, calibration and field rotation are not available with a backend
• -q, --quiet: Hide the progress bar and the summary
• --timings: Print where the time went: wall time per stage and busy time per kind of work
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia calibrate¶

Build master dark, flat and bad-pixel files from calibration captures, for helia stack --dark --flat --bad-pixels

helia calibrate [OPTIONS]

Options:

• --darks <PATH>: Dark captures (lens capped, same exposure and gain as the Sun) (repeatable)
• --flats <PATH>: Flat captures (an even field, at the focus and set-up of the Sun) (repeatable)
• --displaced <PATH>: Captures of the Sun at many places on the sensor (the mount off tracking, or nudged between frames), to solve the flat from instead of from --flats: it then holds the dust and fringes of the observing moment, without a diffuser. The darks (same exposure as the Sun) are taken off first. Needs at least six frames with the limb clear (repeatable)
• --displaced-keep-smooth: With --displaced, keep every scale of the solution, not only the structure finer than a quarter of the displacements (the smooth scales cannot be told from the Sun's own limb darkening unless it moved far)
• --flat-darks <PATH>: Dark captures at the exposure of the flats. Without them the flats keep their offset (or lose the bias, if --bias is given) (repeatable)
• --bias <PATH>: Bias captures (the shortest exposure). Only needed to scale a dark to another exposure (repeatable)
• --lights <CAPTURE>: A light capture: pixels that read the same wrong value in every frame while the Sun moves (stuck pixels) are added to the bad-pixel map. Useful when there are no darks
• -o, --output-dir <DIR>: Folder for master-dark.fits, master-flat.fits, master-bias.fits and bad-pixels.fits (created if needed) (default calibration)
• --combine <COMBINE>: How frames are combined: median, sigma (clip at 3 standard deviations) or sigma:K (default sigma)
• --max-frames <N>: Use at most this many frames per master, spread over the input (default: as many as fit in 3 GiB)
• --no-bad-pixels: Do not look for hot, cold and stuck pixels
• --hot-sigma <K>: A pixel this many robust standard deviations off its neighbours in the dark is hot (default 6)
• --preset <FILTER>: The filter the flats were taken through (ha, cak, ...): adds the advice that goes with it, such as the etalon's sweet spot and Newton rings for H-alpha
• --bayer <BAYER>: Bayer handling: auto, none, rggb, bggr, grbg or gbrg. auto trusts the header, but for a SER file labelled mono it also checks the pixels for a hidden Bayer mosaic (some recorders label raw colour data as mono) and debayers when it finds one. none treats the frames as mono whatever the header or sidecar say; a pattern forces it. For AVI the pattern otherwise comes from the SharpCap sidecar. For FITS frames auto takes BAYERPAT (as stored) and ROWORDER from the header (default auto)
• --bit-depth <BITS>: Bits per sample, instead of the SER header's: 1 to 8 read one byte per pixel, 9 to 16 two bytes. For a header that gets the depth wrong. SER only
• --endian <ORDER>: Byte order of 16-bit samples, instead of the SER header flag (little or big). SER only
• --flip-rows: Read the rows bottom to top, for a file stored upside down. Patterns given to --bayer describe the picture after the flip. SER only
• --row-order <ORDER>: Which way up the rows of FITS frames are stored: auto, top-down or bottom-up. auto follows a ROWORDER card (TOP-DOWN or BOTTOM-UP) when there is one; without it Seestar S50 frames (INSTRUME or TELESCOP names an S50) are top-down and everything else is bottom-up, as the FITS standard says. top-down and bottom-up override the header. --flip-v is a separate edit applied to the result. FITS only (default auto)
• -q, --quiet: Hide the progress messages
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia edit¶

Sharpen and adjust an existing TIFF, PNG or FITS image

helia edit [OPTIONS] --output <OUTPUT> <INPUT>

Arguments:

• <INPUT>: Image to edit: .tif, .tiff, .png or .fits (mono or RGB) (required)

Options:

• -o, --output <OUTPUT>: Output image; the extension picks the format. A colour image stays colour (TIFF or PNG) (required)
• --preset <FILTER>: The filter the image was taken with, for the recommended sharpening values (ha, cak, ...). Without it the filter is read from the file name or folder when possible
• --sharpen <METHOD>: Sharpening: wavelet (Registax-style layers, the usual choice), unsharp, rl (Richardson-Lucy deconvolution) or none. The default is none
• --unsharp-radius <PX>: Unsharp mask: Gaussian radius (sigma) in pixels
• --unsharp-amount <A>: Unsharp mask: how much detail is added back (0.6 is gentle, 2 is strong)
• --unsharp-threshold <T>: Unsharp mask: detail weaker than this (0 to 1) is left alone, so noise is not boosted
• --wavelets <SPEC>: Wavelets as in RegiStax 6: registax:l1=AMOUNT/SHARPEN/DENOISE,l2=..., scheme=dyadic|linear,filter=default|gaussian,initial=N,step=X,linked=on. AMOUNT is the layer slider (0 to 200 %), SHARPEN 0 to 1 (gain is 1 + AMOUNT x SHARPEN, so 100 and 0.14 is 15x), DENOISE 0 to 1.5 (a noise cut of 10 x DENOISE sigmas). Layers not named are left alone. Implies --sharpen wavelet; with --sharpen rl the wavelets run after the deconvolution (deconvolve first, then lift and denoise)
• --wavelet-gains <G1,G2,...>: Wavelets: gain of layers 1, 2, 3 ... (comma separated; 1 leaves a layer alone, above 1 sharpens it). Layers not listed keep the recommended gain
• --wavelet-noise <T1,T2,...>: Wavelets: noise threshold of layers 1, 2, 3 ... in noise sigmas (0 keeps all detail; 2 removes what is not clearly above the noise)
• --rl-iterations <N>: Richardson-Lucy: iterations (more is sharper and noisier)
• --rl-tv <L>: Richardson-Lucy: total-variation weight, 0 to 0.05 (keeps noise from becoming speckle)
• --rl-psf <PSF>: Richardson-Lucy: the blur to undo. auto (from the image scale), limb (measured from the solar limb: best for white light and calcium), gaussian:SIGMA, airy:RADIUS (first dark ring, pixels) or airy-scope:NM,MM,ARCSEC_PER_PX
• --rl-guard <S>: Richardson-Lucy: strength of the limb and sunspot ringing guard, 0 (off) to 1
• --flatten <SOURCE>: Divide the disc by its limb-darkening profile before anything else, so sharpening sees flat contrast: model (the fitted law) or profile (the measured azimuthal median). Outside the limb nothing changes
• --limb-law <LAW>: The limb-darkening law to fit: linear, quadratic (the default) or neckel (Neckel and Labs, five terms). helia stack prints the fit
• --prominence: Composite a stretched prominence layer with the disc: outside the fitted limb the scattered light is taken off and what is left is stretched to read like the disc, joined to it by a feathered edge. For H-alpha and the other lines with prominences. Runs after the sharpening
• --prominence-strength <S>: How hard the prominence layer is lifted: 1 refers it to the brightest prominence found
• --prominence-stretch <K>: The k of the asinh stretch of the layer; 0 is linear, larger lifts the faint parts more (default 6)
• --prominence-level <SHARE>: Brightness of the brightest prominence as a share of the disc's (default 0.75)
• --prominence-feather <SHARE>: Half-width of the feathered join at the limb, as a share of the disc radius (default 0.012)
• --prominence-reach <RADII>: How far out the layer reaches, in disc radii (default 1.4)
• --prominence-gate <SIGMA>: Noise sigmas taken off the layer before the stretch (default 3)
• --prominence-offset <SHARE>: Move the join of layer and disc, as a share of the disc radius added to the fitted limb (negative inside the limb, default 0)
• --prominence-disc-gamma <G>: Gamma of the disc's tone above the sky while the layer is on (default 1: the disc is left alone)
• --prominence-layer-gamma <G>: Gamma of the stretched layer's tone (default 1; above 1 darkens its faint parts)
• --denoise <STRENGTH>: Wavelet denoise; the strength is in noise sigmas for the finest layer (default: the filter's recommended value)
• --denoise-layers <N>: Layers the denoise treats, from the finest
• --black <V>: Levels: input value (0 to 1) that becomes black
• --white <V>: Levels: input value (0 to 1) that becomes white
• --gamma <G>: Levels: mid-tone gamma (above 1 brightens)
• --curve <IN:OUT,...>: A tone curve through IN:OUT points, for example 0.25:0.15,0.75:0.85
• --crop <X,Y,W,H>: Crop to X,Y,W,H in pixels (top-left origin)
• --rotate <DEG>: Rotate clockwise by this many degrees (multiples of 90 are exact)
• --flip-h: Mirror left to right
• --flip-v: Mirror top to bottom. An edit on the finished picture, applied after the capture is read; to correct how FITS frames are read use --row-order
• --resize <SIZE>: Resize: 50% or 0.5, 1200x800, 1200x (width) or x800 (height)
• --edits <NAME|FILE>: Start from a saved edit preset (a name from the presets folder, or a .json file); the options above are added after it
• --save-edits <NAME>: Save the resulting edit list as a preset under this name, for --edits
• --backend <BACKEND>: Compute backend (default auto)
• --plugin-step <SPEC>: Run a step of a plugin: PLUGIN/STEP, optionally followed by :KEY=VALUE,KEY=VALUE or :{"json":"object"} for its parameters. Repeat for several steps, which run in the order given. A frame-op step runs on every frame before stacking (stack only); an image-op step runs on the stack after Helia's own sharpening and edits, or before them when written pre:PLUGIN/STEP; an analyse step reads the result and writes OUTPUT.analysis.json. The plugin must be enabled first (helia plugins enable) (repeatable)
• --stack-backend <PLUGIN>: Stack with this stack-backend plugin instead of on this computer (stack only). The plugin gets the capture and the stacking settings; sharpening, colour and export stay in Helia. True colour, calibration and field rotation are not available with a backend
• -q, --quiet: Hide the summary
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia info¶

Print what a capture file contains: every header field as written, what Helia will use instead where it differs, and why

helia info [OPTIONS] <INPUT>

Arguments:

• <INPUT>: Capture file: .ser or .avi, or a video (.mp4, .mov, .mkv, .webm, .m4v) read through the optional ffmpeg program, or FITS frames: a .fit, .fits or .fts file (a cube or several images in one file), a folder of them, or a pattern such as 'Light_*.fit' (in quotes) (required)

Options:

• --bayer <BAYER>: Bayer handling: auto, none, rggb, bggr, grbg or gbrg. auto trusts the header, but for a SER file labelled mono it also checks the pixels for a hidden Bayer mosaic (some recorders label raw colour data as mono) and debayers when it finds one. none treats the frames as mono whatever the header or sidecar say; a pattern forces it. For AVI the pattern otherwise comes from the SharpCap sidecar. For FITS frames auto takes BAYERPAT (as stored) and ROWORDER from the header (default auto)
• --bit-depth <BITS>: Bits per sample, instead of the SER header's: 1 to 8 read one byte per pixel, 9 to 16 two bytes. For a header that gets the depth wrong. SER only
• --endian <ORDER>: Byte order of 16-bit samples, instead of the SER header flag (little or big). SER only
• --flip-rows: Read the rows bottom to top, for a file stored upside down. Patterns given to --bayer describe the picture after the flip. SER only
• --row-order <ORDER>: Which way up the rows of FITS frames are stored: auto, top-down or bottom-up. auto follows a ROWORDER card (TOP-DOWN or BOTTOM-UP) when there is one; without it Seestar S50 frames (INSTRUME or TELESCOP names an S50) are top-down and everything else is bottom-up, as the FITS standard says. top-down and bottom-up override the header. --flip-v is a separate edit applied to the result. FITS only (default auto)
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia measure¶

Measure how much granulation an image holds: the band-pass contrast (standard deviation over mean) of a disc-centre crop in three bands, for comparing settings on the same capture

helia measure [OPTIONS] <INPUT>

Arguments:

• <INPUT>: Image: .tif, .tiff, .png or .fits (mono or RGB; RGB is averaged to grey) (required)

Options:

• --crop <PX>: Side of the disc-centre crop in pixels (default 240)
• --centre <X,Y>: Centre the crop on this pixel, as X,Y, instead of on the centroid of the bright disc. The centroid moves with prominences and sky glow; give the fitted disc centre from helia stack (its disc: line) to measure the same part of the Sun in every stack of a capture
• --limb: Instead of the granulation bands, fit the limb-darkening laws (linear, quadratic, Neckel and Labs) to the disc and print the coefficients and the measured profile
• --psf: Instead of the granulation bands, measure the blur of the solar limb (the Gaussian sigma --rl-psf limb would use) and print it
• --scale <ARCSEC>: Image scale in arcseconds per pixel, to give sizes in arcseconds
• --aperture <MM>: Telescope aperture in millimetres; with --wavelength and --scale it gives the diffraction cut-off of the power spectrum
• --wavelength <NM>: Wavelength in nanometres (for --aperture)
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia sunspots¶

Find the sunspots on a stacked white-light image: groups, the relative Wolf number and areas corrected for foreshortening, as a table, JSON and an overlay picture

helia sunspots [OPTIONS] <INPUT>

Arguments:

• <INPUT>: Stacked image: .tif, .tiff, .png or .fits (mono or RGB; RGB is averaged to grey), white light, with the whole disc in view (required)

Options:

• --date <TIME>: When the image was taken, UTC, such as 2026-10-20T11:30:00. Gives P, B0 and L0 for the Carrington longitude. Without it, a FITS file's DATE-AVG or DATE-OBS is used, else B0 is taken as 0
• --capture <FILE>: The capture (a .ser) the image was stacked from: its frame timestamps give the time
• --csv <FILE>: Write the spot table as CSV
• --json <FILE>: Write the whole report as JSON
• --overlay <FILE>: Write the overlay picture (spots outlined on the flattened disc) as PNG
• --sunspot-umbra <SHARE>: Umbra threshold: pixels darker than this share of the quiet disc (after the limb darkening is flattened out) are umbra (default 0.55)
• --sunspot-penumbra <SHARE>: Penumbra threshold: pixels darker than this share of the quiet disc are spot. Raise it to take in fainter penumbrae and pores (default 0.88)
• --sunspot-min-area <MSH>: Smallest spot to keep, in millionths of the visible hemisphere (default 2)
• --sunspot-max-area <MSH>: Largest spot, in millionths of the hemisphere; a dark region bigger than this (a cloud, a vignette) is left out (default 6000)
• --sunspot-group-gap <DEG>: Spots whose edges are closer than this on the Sun, in degrees, form one group (default 3)
• --wolf-k <K>: Observer factor k of the Wolf number R = k (10 g + s) (default 1)
• --north-angle <DEG>: How far solar north is turned counter-clockwise from the top of the image, in degrees. Default 0: solar north up (default 0)
• --celestial-north-up: The image has celestial north up (an equatorial mount): solar north is then turned by the position angle P of the Sun at the capture time, added to --north-angle
• --mirror: The image is a mirror image (west is on the left)
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia timelapse¶

Make a time-lapse: stack each capture with the same settings, register the stacks to each other (limb fit and phase correlation of the disc centre), optionally even out the brightness, and write a numbered PNG or TIFF sequence and a movie (MP4 through ffmpeg, else an animated PNG)

helia timelapse [OPTIONS] --output <DIR> <CAPTURES>... [-- <STACK OPTIONS>...]

Arguments:

• <CAPTURES>: The captures to stack (.ser, .avi, or a video), or images already stacked (.tif, .tiff, .png, .fits): one per frame. They are put in time order when every one has a time (see --date), else kept as given (required; repeatable)
• <STACK OPTIONS>: Stack settings, after --: everything helia stack takes except the input and the output, such as -- --preset ha --keep 25%. Every capture is stacked with the same ones (repeatable)

Options:

• -o, --output <DIR>: Directory for the output: frame-0001.png and so on, timelapse.mp4 (or timelapse.png when it is an animated PNG), timelapse.csv, and the stacks in stacks/. Created when it does not exist (required)
• --report <DIR>: Write the diagnostics of the series into this directory (created): how each frame was registered (shift, method, limb fit confidence, phase correlation), the brightness before and after --deflicker, and, with --derotate, how far the Sun's rotation moved the surface of each frame; each as a PNG with its numbers as CSV and JSON, and report.html
• --format <FORMAT>: Format of the numbered frames: png (8-bit, for sharing) or tiff (16-bit) (default png)
• --movie <KIND>: The movie: auto (MP4 when ffmpeg is installed, else an animated PNG), mp4 (an error without ffmpeg), apng (needs nothing else) or none (default auto)
• --fps <FPS>: Frames a second of the movie (default 10)
• --reference <FRAME>: The frame the others are registered to: first, middle or a number from 1 (default middle)
• --no-refine: Register by the limb fit alone, without the phase correlation of the disc centre that refines it
• --max-refine <PX>: Largest correction in pixels the phase correlation may make to the limb shift; a bigger one is taken for a false lock and ignored (default 3)
• --deflicker <DEFLICKER>: Even out the brightness of the frames: off, match or smooth (default off)
• off: Leave the brightness alone
• match: Bring every frame to the median brightness of the series
• smooth: Bring every frame to the median of the frames around it (--deflicker-window): flicker goes, a slow change stays
• --deflicker-window <N>: Frames in the running median of --deflicker smooth (odd, at least 3) (default 5)
• --crop: Cut every frame to the area all of them cover, so there are no empty edges where a frame was moved
• --date <DATE>: The UTC date of the captures (YYYY-MM-DD) for file names that hold only the time of day, such as SharpCap's 15_32_09.avi
• --utc-offset <HOURS>: Hours east of UTC of the clock that named the files (1 for British Summer Time), when their names give local time (default 0)
• --derotate: Bring every frame to one time by the Sun's differential rotation, so the surface features hold still as the series plays (needs the time of every capture). By default to the time of the reference frame; see --derotate-to
• --derotate-to <TIME>: The time to derotate to, UTC, such as 2026-10-20T14:30:00 (implies --derotate)
• --rotation-law <LAW>: The rotation law: howard (Howard, Harvey and Forgach 1990, sunspots and plage), snodgrass (Snodgrass and Ulrich 1990, Doppler features) or your own A,B,C in degrees a day for A + B sin^2 + C sin^4 of the latitude (default howard)
• --north-angle <DEG>: How far solar north is turned counter-clockwise from the top of the image, in degrees. Default 0: solar north up (default 0)
• --celestial-north-up: The images have celestial north up (an equatorial mount): solar north is then turned by the position angle P of the Sun at each image's time, added to --north-angle
• --mirror: The images are mirror images (west is on the left)
• --raw-brightness: Move the pixel values as they are. By default the contrast against the limb darkening goes with each feature, so a feature that moves toward the limb is not dimmed twice
• --no-sort: Keep the captures in the order given instead of sorting them by time
• --reuse-stacks: Use a stack already in DIR/stacks instead of stacking its capture again (to try other registration settings quickly)
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia solar-derotate¶

Bring images of the Sun to one time by its differential rotation (Howard or Snodgrass rates, P, B0 and L0 from the capture times), so that features line up across a long session or between panels taken minutes apart

helia solar-derotate [OPTIONS] --output <DIR> <IMAGES>...

Arguments:

• <IMAGES>: The images to derotate (.tif, .tiff, .png, .fits): stacks, or panels of a mosaic. Each needs a time (see --date) and the whole disc in view (required; repeatable)

Options:

• -o, --output <DIR>: Directory for the derotated images, named NAME-derotated.EXT; created when it does not exist (required)
• --to <TIME>: The time to bring every image to: first, middle or last (of the images, by time), or a UTC time such as 2026-10-20T14:30:00 (default middle)
• --date <DATE>: The UTC date of the images (YYYY-MM-DD) for file names that hold only the time of day
• --utc-offset <HOURS>: Hours east of UTC of the clock that named the files, when their names give local time (default 0)
• --rotation-law <LAW>: The rotation law: howard (Howard, Harvey and Forgach 1990, sunspots and plage), snodgrass (Snodgrass and Ulrich 1990, Doppler features) or your own A,B,C in degrees a day for A + B sin^2 + C sin^4 of the latitude (default howard)
• --north-angle <DEG>: How far solar north is turned counter-clockwise from the top of the image, in degrees. Default 0: solar north up (default 0)
• --celestial-north-up: The images have celestial north up (an equatorial mount): solar north is then turned by the position angle P of the Sun at each image's time, added to --north-angle
• --mirror: The images are mirror images (west is on the left)
• --raw-brightness: Move the pixel values as they are. By default the contrast against the limb darkening goes with each feature, so a feature that moves toward the limb is not dimmed twice
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia derotate¶

Turn stacked images of one target to the same orientation, undoing the field rotation of an altazimuth mount between captures (a time-lapse)

helia derotate [OPTIONS] --output-dir <DIR> <INPUTS>...

Arguments:

• <INPUTS>: The images, .fits, .tif or .png, of one session (mono or RGB). Each is turned to the orientation of the reference image (required; repeatable)

Options:

• -o, --output-dir <DIR>: Folder to write the turned images to, as NAME-derot.EXT; created if it does not exist (required)
• --site <LAT,LON,ALT>: Observing site as LAT,LON,ALT (degrees north, degrees east, metres). Without it the HELIA_SITE environment variable is used
• --times <TIME,...>: When each image was taken, UTC, comma separated, in the order of the images (2026-10-20T11:30:00,2026-10-20T11:45:00). A FITS file's DATE-AVG or DATE-OBS is used for an image that this leaves out (repeatable)
• --reference <WHICH>: The orientation to turn the others to: middle (of the session, the default), first, last, or the number of an image (from 1) (default middle)
• --mirror: The pictures are mirror images (an odd number of reflections, a star diagonal for one): the turn is the other way
• --overwrite: Overwrite files that exist
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia mosaic¶

Join panels of the Sun into a full-disc mosaic: match the overlaps (shift and a few degrees of turn), place all the panels at once by least squares, match their brightness, join along seams of least difference and feather the seams. The panels can be derotated to one time first

helia mosaic [OPTIONS] --output <FILE> <PANELS>... [-- <STACK OPTIONS>...]

Arguments:

• <PANELS>: The panels: captures (.ser, .avi, a video) to stack, or images already stacked (.tif, .tiff, .png, .fits); at least two, each sharing a strip of the Sun with a neighbour. The first is the reference: the mosaic is in its orientation and brightness (required; repeatable)
• <STACK OPTIONS>: Stack settings, after --: everything helia stack takes except the input and the output. Every capture is stacked with the same ones (repeatable)

Options:

• -o, --output <FILE>: The mosaic to write; the extension picks the format (.tif, .png or .fits). The panel and pair tables are written beside it as NAME-panels.csv and NAME-pairs.csv, and the stacks made from captures in NAME-stacks/ (required)
• --max-rotation <DEG>: The most the panels may be turned against each other, in degrees; 0 holds them all square to the first (default 4)
• --min-overlap <PERCENT>: The least overlap that counts, as a percentage of the smaller panel (default 5)
• --min-correlation <R>: The least normalised correlation of the detail on an overlap for a pair to be believed, 0 to 1 (default 0.45)
• --feather <PX>: Width in pixels of the blend across a seam and at a panel's edge (default 12)
• --no-gain-match: Do not match the panels' gain and offset on their overlaps
• --no-seams: Do not search for seams of least difference: blend by the distance from each panel's edge
• --derotate: Bring every panel to one time by the Sun's differential rotation before joining them (needs the time of every panel and enough of the limb in the mosaic to fit the disc). By default to the middle time; see --derotate-to
• --derotate-to <TIME>: The time to derotate to: first, middle or last (of the panels, by time), or a UTC time such as 2026-10-20T14:30:00 (implies --derotate)
• --rotation-law <LAW>: The rotation law: howard (Howard, Harvey and Forgach 1990, sunspots and plage), snodgrass (Snodgrass and Ulrich 1990, Doppler features) or your own A,B,C in degrees a day for A + B sin^2 + C sin^4 of the latitude (default howard)
• --north-angle <DEG>: How far solar north is turned counter-clockwise from the top of the image, in degrees. Default 0: solar north up (default 0)
• --celestial-north-up: The images have celestial north up (an equatorial mount): solar north is then turned by the position angle P of the Sun at each image's time, added to --north-angle
• --mirror: The images are mirror images (west is on the left)
• --raw-brightness: Move the pixel values as they are. By default the contrast against the limb darkening goes with each feature, so a feature that moves toward the limb is not dimmed twice
• --date <DATE>: The UTC date of the panels (YYYY-MM-DD) for file names that hold only the time of day
• --utc-offset <HOURS>: Hours east of UTC of the clock that named the files, when their names give local time (default 0)
• --reuse-stacks: Use a stack already in NAME-stacks instead of stacking its capture again
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plot¶

Draw one science figure again from a report directory that helia stack --report wrote (or stack a capture and draw it)

helia plot [OPTIONS] <KIND> <INPUT> [-- <STACK OPTIONS>...]

Arguments:

• <KIND>: Which figure: quality-sorted, quality-order, quality-histogram, shift-drift, seeing-time, ap-grid, ap-quality, ap-shift, ap-field, ap-residual, power-spectrum, mtf, limb-profile, limb-psf, histogram, noise-snr, grid-stonyhurst, grid-carrington, timelapse-registration, timelapse-brightness or timelapse-derotation; or all (required)
• <INPUT>: A report directory written by helia stack --report, or a capture (.ser, .avi, a video, FITS frames), which is stacked first with the options after -- (required)
• <STACK OPTIONS>: Options for helia stack when INPUT is a capture, after --, for example -- --keep 10% --preset ha (repeatable)

Options:

• -o, --output <FILE>: Where to write the PNG (default: the figure's name in the current directory). With all, a directory (default: the current one)
• --size <WxH>: Size in pixels, WIDTHxHEIGHT (default 960x540)
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia serve¶

Run the HTTP/JSON API server

helia serve [OPTIONS]

Options:

• --bind <BIND>: Address to listen on; a non-loopback address needs a token (default 127.0.0.1:7870)
• --data-root <DIR>: Directory all request paths must stay inside (default: the current directory)
• --token <TOKEN>: Bearer token. Visible in the process list; prefer --token-file or the HELIA_TOKEN environment variable
• --token-file <FILE>: File holding the bearer token
• --workers <WORKERS>: Jobs that run at once (default 1)
• --max-queue <MAX_QUEUE>: Queued plus running jobs allowed before answering 429 (default 16)
• --cors-origin <ORIGIN>: Allow browser access from this origin (repeatable). Off by default
• --cache-dir <DIR>: Directory for compressed video decoded by ffmpeg (default: the operating system's cache directory, or HELIA_CACHE_DIR)
• --allow-host <HOST>: Accept this Host header on a loopback bind (repeatable), e.g. behind a proxy
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia presets¶

List the filter presets (helia stack --preset ...)

helia presets [OPTIONS]

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia lut¶

Write a filter's colour table as a file other programs read (.cube, .csv, ImageJ .lut or a PNG strip), so a picture coloured elsewhere matches one coloured by Helia

helia lut [OPTIONS] --output <OUTPUT> <PRESET>

Arguments:

• <PRESET>: The filter whose colour look to write (ha, cak, cah, mg, na, he-d3, hbeta, white); see helia presets (required)

Options:

• -o, --output <OUTPUT>: Output file. The extension picks the format: .cube, .csv, .lut (ImageJ) or .png, unless --format says (required)
• --format <FORMAT>: File format: cube, csv, imagej or png
• --size <N>: Entries in the table, 2 to 4096 (an ImageJ table always has 256) (default 256)
• --invert: Invert the picture before colouring (the table runs from white to black)
• --strength <S>: Mix of colour and grey from 0 to 1 (default 1)
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia feedback¶

Send feedback (a bug, a feature request or a question). It is sent to the Helia developers and filed in the Helia issue tracker, through the feedback service

helia feedback [OPTIONS] --title <TITLE>

Options:

• --kind <KIND>: What kind of feedback this is (default bug)
• bug: Something is broken or wrong
• feature: A request for something new
• question: A question about using Helia
• other: Anything else
• --title <TITLE>: One line that says what it is (at most 120 characters) (required)
• --description <DESCRIPTION>: The details (at most 8000 characters). - reads standard input (default ``)
• --screenshot <FILE.png>: A PNG screenshot to attach (at most 5 MiB; larger ones are shrunk). Check it shows nothing private: it is filed in the issue tracker
• --highlight <X,Y,W,H>: A rectangle to highlight on the screenshot, as x,y,w,h in its pixels (repeatable)
• --system-info: Include system details: Helia version, commit and target, and your operating system. Never a host name, user name or path
• --url <URL>: Feedback service address (default: HELIA_FEEDBACK_URL, else the public service at feedback.discworld.casa)
• --dry-run: Show the report that would be sent, and send nothing
• --save <FILE.zip>: If the service cannot be reached, also save the report to this .zip
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins¶

List, inspect, approve, set up and test plugins: programs that add a processing step or do the stacking elsewhere. Nothing runs until you enable it

helia plugins [OPTIONS] <COMMAND>

Subcommands:

• list: List the plugins Helia found (in the plugins folder and named with --plugin) and whether each is on. Finding a plugin only lists it; nothing runs until you enable it
• info: Show everything about one plugin: where it is, its checksums, what it can do, its settings and the steps it offers
• enable: Approve a plugin and switch it on. Shows where it comes from, its SHA-256 and what it asks for, and asks you to confirm. A plugin runs with your rights, not in a sandbox. If its program or manifest changes later, it is switched off until you enable it again
• disable: Switch a plugin off. Its settings are kept
• forget: Forget a plugin: its approval and its settings
• set: Set the plugin's settings, KEY=VALUE pairs checked against its settings form. A value of - for a secret reads it from standard input, so it stays out of your shell history
• test: Start a plugin and run its own check (for example, can it reach its server), then show its log. The plugin must be enabled

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins list¶

List the plugins Helia found (in the plugins folder and named with --plugin) and whether each is on. Finding a plugin only lists it; nothing runs until you enable it

helia plugins list [OPTIONS]

Options:

• --json: Print JSON instead of a table
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins info¶

Show everything about one plugin: where it is, its checksums, what it can do, its settings and the steps it offers

helia plugins info [OPTIONS] <NAME>

Arguments:

• <NAME>: Plugin name, as helia plugins list shows it (required)

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins enable¶

Approve a plugin and switch it on. Shows where it comes from, its SHA-256 and what it asks for, and asks you to confirm. A plugin runs with your rights, not in a sandbox. If its program or manifest changes later, it is switched off until you enable it again

helia plugins enable [OPTIONS] <NAME>

Arguments:

• <NAME>: Plugin name (required)

Options:

• -y, --yes: Do not ask. The checksum is still recorded
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins disable¶

Switch a plugin off. Its settings are kept

helia plugins disable [OPTIONS] <NAME>

Arguments:

• <NAME>: Plugin name (required)

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins forget¶

Forget a plugin: its approval and its settings

helia plugins forget [OPTIONS] <NAME>

Arguments:

• <NAME>: Plugin name (required)

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins set¶

Set the plugin's settings, KEY=VALUE pairs checked against its settings form. A value of - for a secret reads it from standard input, so it stays out of your shell history

helia plugins set [OPTIONS] <NAME> <KEY=VALUE>...

Arguments:

• <NAME>: Plugin name (required)
• <KEY=VALUE>: The settings to change (required; repeatable)

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia plugins test¶

Start a plugin and run its own check (for example, can it reach its server), then show its log. The plugin must be enabled

helia plugins test [OPTIONS] <NAME>

Arguments:

• <NAME>: Plugin name (required)

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia update¶

Check for a newer Helia, download it and install it, or go back to the previous version. Contacts the update server only when you run it

helia update [OPTIONS] <COMMAND>

Subcommands:

• check: Ask the update server whether a newer Helia exists
• apply: Download the newer Helia and install it
• status: Show the update settings, how this copy is installed and what is remembered
• rollback: Go back to the version an update replaced, when it was kept
• config: Show or change the update mode and channel

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia update check¶

Ask the update server whether a newer Helia exists.

Exit code 0: up to date. 10: an update is available. 12: the update details need a newer Helia to read. 1: the check failed.

helia update check [OPTIONS]

Options:

• --channel <CHANNEL>: Look at this channel for this run only (the saved channel is unchanged)
• stable: Released versions only
• prerelease: Pre-release versions as well
• --json: Print the answer as JSON
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia update apply¶

Download the newer Helia and install it.

How it installs depends on how this copy was installed: an AppImage is replaced (the old file is kept beside it), the Windows installer is run silently when this command ends, and for deb and rpm installs the package command is shown and no file is touched.

helia update apply [OPTIONS]

Options:

• -y, --yes: Go ahead without asking
• --channel <CHANNEL>: Use this channel for this run only
• stable: Released versions only
• prerelease: Pre-release versions as well
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia update status¶

Show the update settings, how this copy is installed and what is remembered

helia update status [OPTIONS]

Options:

• --json: Print as JSON
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia update rollback¶

Go back to the version an update replaced, when it was kept

helia update rollback [OPTIONS]

Options:

• -y, --yes: Go ahead without asking
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia update config¶

Show or change the update mode and channel.

The mode is notify (the default: tell me, download when I ask), automatic (download and install on restart) or off (never check on my own). With no option this shows the current settings.

helia update config [OPTIONS]

Options:

• --mode <MODE>: Set the mode
• notify: Tell me when an update is available; download only when asked
• automatic: Download updates and install them when Helia restarts
• off: Never check on my own
• --channel <CHANNEL>: Set the channel
• stable: Released versions only
• prerelease: Pre-release versions as well
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia tools¶

Install, check and remove optional programs such as ffmpeg. Nothing is installed without your say-so: the provider's full licence is shown and you must type yes before anything is downloaded

helia tools [OPTIONS] <COMMAND>

Subcommands:

• status: Show which optional tools are installed and where Helia finds ffmpeg
• licence: Print the full licence text of a tool, with its provider and source link
• install: Install a tool: show its licence, ask, then fetch it from the provider
• remove: Remove an installed tool

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia tools status¶

Show which optional tools are installed and where Helia finds ffmpeg.

Uses no network. Helia looks for ffmpeg in HELIA_FFMPEG and HELIA_FFPROBE first, then in a copy installed with helia tools install, then on the PATH.

helia tools status [OPTIONS]

Options:

• --json: Print as JSON
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia tools licence¶

Print the full licence text of a tool, with its provider and source link.

Fetches the signed list of tools to get the text. Nothing is installed.

helia tools licence [OPTIONS] <ITEM>

Arguments:

• <ITEM>: The tool: ffmpeg (required)

Options:

• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia tools install¶

Install a tool: show its licence, ask, then fetch it from the provider.

You are shown the provider, the size, the source link and the whole licence (in a pager when there is a terminal) and must type yes. Declining leaves everything as it was and Helia keeps working without the tool. Exit code 3: the licence was not accepted.

helia tools install [OPTIONS] <ITEM>

Arguments:

• <ITEM>: The tool: ffmpeg (installs ffmpeg and ffprobe) (required)

Options:

• --method <METHOD>: How to get it: the package manager, a download, or choose for me (default auto)
• auto: Use the system package manager when there is one (Linux, Homebrew), else download
• package: Use the system package manager; its command is shown and run only if you agree
• download: Download the provider's own build into your Helia tools folder
• --accept-licence <HASH>: Accept the licence without a prompt, for scripts: the first 12 or more characters of the licence hash that helia tools licence prints. If the licence text has changed since you read it, the hash differs and nothing is installed
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)

helia tools remove¶

Remove an installed tool.

Deletes the copy in your Helia tools folder. A tool installed by a package manager is left on the system (Helia says how to remove it); only Helia's note of it is dropped.

helia tools remove [OPTIONS] <ITEM>

Arguments:

• <ITEM>: The tool: ffmpeg (required)

Options:

• --forget-licence: Also forget that you accepted its licence, so installing again asks again
• -y, --yes: Go ahead without asking
• --plugin <PATH>: A plugin to list for this run: a folder holding plugin.toml, or the manifest itself. Repeat for several. A plugin named here is only listed; it runs after you enable it (helia plugins enable). For plugins you are writing or keep outside the plugins folder (repeatable)