Skip to content

API reference

Solar lucky-imaging stacker. All paths are relative to the server's data root. Version 0.8.2 of the document; licence GPL-3.0-or-later.

The narrative guide, with examples and the security model, is in The API. The machine-readable document is openapi.json, and a running server serves it at /api/v1/openapi.json.

All paths below are relative to /api/v1.

Operations

GET /captures/frame

One frame of a capture as an auto-stretched 8-bit greyscale PNG.

Parameter In Type Required Description
path query string yes Capture path relative to the data root.
index query integer no Frame index (default 0).
channel query ChannelArg no r, g, b or lum (default) for Bayer captures.
max_width query integer no Downscale to at most this width (16 to 8192).
bayer query string no Bayer handling, as for jobs: auto (default), none or a pattern.
bit_depth query integer (int32) no Bits per sample instead of the SER header's.
endian query string no little or big.
flip_rows query boolean no Read the rows bottom to top.
row_order query string no Row order of FITS frames: auto (default), top-down or bottom-up.
Status Meaning Body
200 8-bit greyscale PNG image/png

POST /captures/inspect

Header information for a .ser, .avi or video capture, without reading frames.

Request body:

Status Meaning Body
200 OK application/json: CaptureInfo

GET /docs

A small HTML page that lists the operations of the OpenAPI document; needs no token.

Needs no token.

Status Meaning Body
200 OK text/html

GET /health

Liveness probe. Always answers {"status":"ok"}; needs no token.

Needs no token.

Status Meaning Body
200 OK application/json: Health

GET /jobs

Remembered jobs, oldest first. The newest 100 finished jobs are kept.

Status Meaning Body
200 OK application/json: array of JobView

POST /jobs

Queue a stack. Answers 202 with the job; poll it or follow its events.

Request body:

Status Meaning Body
202 Accepted application/json: JobView
429 queue full (queue_full) application/json: ErrorEnvelope

GET /jobs/{id}

One job: state, stage, progress, timings and summary.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
200 OK application/json: JobView
404 unknown job id application/json: ErrorEnvelope

DELETE /jobs/{id}

Cancel a queued or running job, or forget a finished one.

A finished job's output file stays on disk.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
202 cancellation requested application/json: JobView
204 finished job forgotten
404 unknown job id application/json: ErrorEnvelope

GET /jobs/{id}/events

WebSocket stream of job events: a snapshot, then state and progress messages.

The server closes the stream after the final state message.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
101 WebSocket; text frames are JobEvent JSON

GET /jobs/{id}/preview.png

An 8-bit PNG of the result (square-root stretch). Only once the job has succeeded.

Parameter In Type Required Description
id path integer (int64) yes job id
max_width query integer no Downscale to at most this width (16 to 8192; stored previews are at most 2048 wide).
Status Meaning Body
200 PNG preview image/png
409 the job has not succeeded (not_ready) application/json: ErrorEnvelope

GET /jobs/{id}/report

The science report of a finished job that asked for report: one self-contained HTML page with the figures, tables and settings.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
200 the report page text/html
404 the job did not ask for a report (report_missing) application/json: ErrorEnvelope
409 the job has not succeeded (not_ready) application/json: ErrorEnvelope

GET /jobs/{id}/report/{file}

One file of the science report: a figure (quality-sorted.png), its data (frame-quality.csv, frame-quality.json) or fits-header.txt. The files are listed in summary.report.files.

Parameter In Type Required Description
id path integer (int64) yes job id
file path string yes file name from summary.report.files
Status Meaning Body
200 the file, with the matching content type
404 no such report or file (report_missing, report_file_missing) application/json: ErrorEnvelope
409 the job has not succeeded (not_ready) application/json: ErrorEnvelope

GET /jobs/{id}/result

The written TIFF or FITS file, streamed. Only once the job has succeeded.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
200 the stacked TIFF, PNG or FITS file
409 the job has not succeeded (not_ready) application/json: ErrorEnvelope

GET /jobs/{id}/sunspots.csv

The sunspot table of a finished job that asked for sunspots, as CSV.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
200 one row per spot text/csv
404 the job did not ask for sunspots (sunspots_missing) application/json: ErrorEnvelope
409 the job has not succeeded (not_ready) application/json: ErrorEnvelope

GET /jobs/{id}/sunspots.png

The sunspot overlay of a finished job that asked for sunspots: the flattened disc with penumbra, umbra and group numbers drawn on it.

Parameter In Type Required Description
id path integer (int64) yes job id
Status Meaning Body
200 overlay PNG image/png
404 the job did not ask for sunspots (sunspots_missing) application/json: ErrorEnvelope
409 the job has not succeeded (not_ready) application/json: ErrorEnvelope

POST /mosaic

Join panels of the Sun into a full-disc mosaic.

Stack every panel first, with the same settings, using ordinary jobs. The request runs to the end before it answers.

Request body:

Status Meaning Body
200 OK application/json: MosaicResponse
409 output exists and overwrite is false (output_exists) application/json: ErrorEnvelope
422 bad settings, panels that do not match, or no time for a derotation application/json: ErrorEnvelope

GET /openapi.json

This API as an OpenAPI document.

Status Meaning Body
200 OpenAPI 3 document

GET /presets

GET /presets: the filter presets, their recommended settings and colours.

Status Meaning Body
200 OK application/json: PresetList

GET /presets/{id}/lut

A preset's colour table as a file other programs read.

Parameter In Type Required Description
id path string yes preset id, see GET /presets
format query string no cube (default), csv, imagej or png.
size query integer no Entries, 2 to 4096 (default 256; an imagej table always has 256).
invert query boolean no Invert before colouring.
strength query number (float) no Mix of colour and grey, 0 to 1 (default 1).
Status Meaning Body
200 the table: a .cube, .csv, ImageJ .lut or a PNG strip
404 no such preset application/json: ErrorEnvelope
422 a bad format, size or strength application/json: ErrorEnvelope

POST /solar-derotation

Bring images of the Sun to one time by its differential rotation.

Each image is derotated on its own, about the disc fitted to it; the result is not shifted, so use the time-lapse (or a mosaic) to register them.

Request body:

Status Meaning Body
200 OK application/json: SolarDerotationResponse
409 a result exists and overwrite is false (output_exists) application/json: ErrorEnvelope
422 bad settings, no time, or no clear disc application/json: ErrorEnvelope

POST /timelapse

Register stacked images to each other and write a time-lapse: numbered frames, a registration table and a movie.

Stack every capture first, with the same settings, using ordinary jobs. The request runs to the end before it answers; a long series with an MP4 can take a while.

Request body:

Status Meaning Body
200 OK application/json: TimelapseResponse
409 output already holds a time-lapse and overwrite is false (output_exists) application/json: ErrorEnvelope
422 bad settings, fewer than two inputs, or an input that is not a stacked image application/json: ErrorEnvelope

GET /version

Server version, backend availability, limits and whether a token is required.

The GPU is probed once, on first use.

Status Meaning Body
200 OK application/json: VersionInfo

Schemas

AlignmentSummary

Global alignment: the method that ran, why, and its confidence.

Field Type Required Description
confidence number (float), may be null no Mean confidence of the frames, 0 to 1. Absent when it was not measured.
confidence_min number (float), may be null no Least confidence of any frame, 0 to 1.
fallbacks integer yes Frames that wanted the limb fit but were aligned by phase correlation.
limb array of number (float), may be null no Fitted limb of the reference: centre x, centre y and radius, pixels.
method string yes What ran: limb or phase.
reason string yes Why, in a sentence (for auto, whether the full disc was in view).
requested string yes What config.align asked for: auto, phase or limb.
sampled boolean yes The confidence comes from a sample of the frames (a GPU run).

AutoApSummary

What automatic alignment points chose and what they were based on.

Field Type Required Description
arcsec_per_pixel number (float), may be null no Image scale from the fitted limb, arcseconds per pixel. Absent when there was no limb.
search_radius integer yes Search radius around the global shift, pixels.
size integer yes Window edge, pixels.
step integer yes Distance between window centres, pixels.
text string yes The choice in a sentence.
warp_px number (float), may be null no Local warp of the seeing, pixels (root mean square distance of an alignment point's shift from its frame's median). Absent when too few points locked.

BackendArg

Compute backend request.

One of auto, cpu, gpu.

Backends

Backend availability.

Field Type Required Description
cpu CpuInfo yes CPU reference path.
gpu GpuInfo yes wgpu path.

BuildDetails

How the server binary was built.

Field Type Required Description
built string yes Build time, UTC.
commit string yes Short git commit hash (unknown outside a git checkout).
dirty boolean yes Built from a tree with uncommitted changes.
profile string yes Cargo profile.
rust string yes Compiler version.
target string yes Target triple.
wgpu string yes wgpu version.

CalibrationConfig

Calibration masters for a job. Each path is relative to the data root and names a master file (FITS, from helia calibrate) or raw calibration frames to build one from (a SER, AVI or FITS file, or a folder of them).

Field Type Required Description
bad_pixels string, may be null no Bad-pixel map: a FITS map from helia calibrate, or a text file with an x y pair (from 0, top-left) on each line.
bias string, may be null no Master bias, or bias captures. Only used with scale_dark.
combine string no How frames are combined into a master: median, sigma or sigma:K. Default sigma. Default "sigma".
cosmetic boolean no Without bad_pixels, find the hot pixels of the dark and the cold ones of the flat and correct them. Default true. Default true.
dark string, may be null no Master dark, or dark captures.
displaced string, may be null no Captures of the Sun at many places on the sensor, to solve a flat from when there is no flat (self-calibration: dust and fringes included). The dark is taken off first. Excludes flat.
flat string, may be null no Master flat, or flat captures.
flat_dark string, may be null no Dark captures at the exposure of the flats, when flat is captures.
scale_dark boolean no Scale the dark by the ratio of the exposures (read from the SharpCap sidecar of the capture). Default false.

CaptureInfo

Header information for a capture.

Field Type Required Description
bayer string, may be null no Bayer pattern (rggb ...) when raw colour.
bit_depth integer (int32) yes Bits per sample.
codec string, may be null no Video codec (h264, ...), for video read through ffmpeg.
colour string yes Pixel layout: mono, bayer, rgb, bgr, or video for compressed video, which ffmpeg converts to luminance or one colour channel.
detection DetectionInfo or null no
effective EffectiveInfo yes What Helia decodes the capture with, and where each value came from.
format string yes ser, avi, or the extension of a video read through ffmpeg (mp4, mov, mkv, webm, m4v; also avi for a compressed AVI).
fourcc string, may be null no AVI FourCC.
frame_rate number (double), may be null no Frames per second, for video.
frames integer yes Number of frames.
header SerHeaderInfo or null no
height integer (int32) yes Height in pixels.
instrument string, may be null no SER instrument string.
notices array of NoticeInfo yes What to tell the user about how the file was read.
observer string, may be null no SER observer string.
overrides array of string yes The overrides in force, as command-line flags.
path string yes Capture path relative to the data root.
quality_note string, may be null no Quality caveat when the input is lossy video, for example "lossy 8-bit 4:2:0 video (h264): fine for quick results, SER/AVI raw captures keep more detail".
recommended Recommended yes The settings a job would use if none were given.
sidecar SidecarInfo or null no
telescope string, may be null no SER telescope string.
timestamps boolean, may be null no SER per-frame timestamps present.
width integer (int32) yes Width in pixels.

ChannelArg

Colour plane taken from a Bayer capture.

One of r, g, b, lum.

ChannelSummary

How red and blue were registered to green in a true-colour stack.

Field Type Required Description
applied boolean yes The plane was moved. False when the shift was too small, too large or not trustworthy.
channel string yes red or blue.
confidence number (float) yes Confidence of the correlation, 0 to 1.
shift array of number (float) yes Shift measured, pixels: [dx, dy].

CpuInfo

CPU availability (always true).

Field Type Required Description
available boolean yes Always true.

DebayerArg

Demosaicing method.

One of bilinear, mhc.

DerotateConfig

How the Sun's differential rotation is undone (derotate of a time-lapse, and the settings of POST /solar-derotation); every field is optional.

Field Type Required Description
celestial_north_up boolean no The images have celestial north up: solar north is turned by the position angle P at each image's time, on top of north_angle_deg. Default false.
law string, may be null no howard (default), snodgrass, or A,B,C: degrees a day for A + B sin^2 + C sin^4 of the latitude (A positive).
mirror boolean no The images are mirror images (west on the left). Default false.
north_angle_deg number (float) no Degrees counter-clockwise from the top of the image to solar north (default 0). Default 0.0.
raw_brightness boolean no Move the pixel values as they are, not the contrast against the limb darkening. Default false.
to string, may be null no The time to bring every image to, UTC (YYYY-MM-DDThh:mm:ss). Default: the reference frame's time in a time-lapse, the middle time of the images in POST /solar-derotation (which also takes first, middle and last).

DerotatedImage

One derotated image.

Field Type Required Description
centre_shift_px number (float) yes The same at the disc centre.
disc array of number (double) yes The disc found in the input: centre x, centre y, radius, pixels.
dt_s number (double) yes Seconds moved, positive forward.
file string yes The result, relative to the data root.
input string yes The input.
max_shift_px number (float) yes The most any pixel of the disc came from, pixels.
time string yes The input's time, UTC.

DetectionInfo

The test for a hidden Bayer mosaic.

Field Type Required Description
frames_used integer yes Frames measured.
pattern string, may be null no Pattern found, for mosaic.
position_means array of number (double) yes Mean level (0 to 1) of the pixels at even x/even y, odd x/even y, even x/odd y and odd x/odd y.
reason string, may be null no Why it could not tell, for inconclusive.
red_blue_basis string, may be null no How red was told from blue, for mosaic.
region array of integer yes Area measured: x, y, width, height.
spread number (double) yes (largest - smallest) / average of the four means.
verdict string yes mosaic, mono or inconclusive.

EffectiveInfo

What Helia decodes the capture with.

Field Type Required Description
bayer SourcedText yes Bayer pattern (rggb ...), or none for mono.
bit_depth SourcedNumber yes Bits per sample.
byte_order SourcedText yes Byte order of 16-bit samples: little or big.
flip_rows SourcedFlag yes Rows are read bottom to top.

ErrorBody

Machine-readable error body.

Field Type Required Description
code string yes Stable snake_case identifier, safe to match on.
message string yes Human-readable explanation.

ErrorEnvelope

Envelope returned for every non-2xx response.

Field Type Required Description
error ErrorBody yes The error.

FieldRotationConfig

How to undo the field rotation of an altazimuth mount.

Field Type Required Description
mirror boolean no The picture is a mirror image (an odd number of reflections): the turn is the other way. Default false.
reference string, may be null no The orientation every frame is turned to: middle (default), first or last.

FieldRotationSummary

What undoing the field rotation did.

Field Type Required Description
altitude_deg number (double) yes Altitude of the Sun at the reference, degrees.
frames_stamped integer yes Frames that had a timestamp of their own.
limb_shift_px number (float), may be null no Displacement at the limb, pixels, of the frame that turned most; absent without a fitted limb.
lines array of string yes The report in lines, as the command line prints it.
max_turn_deg number (double) yes Largest turn applied to a frame, degrees.
rate_deg_per_min number (double) yes Mean rate of rotation, degrees per minute.
reference_angle_deg number (double) yes Parallactic angle at the reference, degrees.
reference_time string yes The orientation every frame was turned to: the time of that frame, ISO 8601 UTC.
span_deg number (double) yes Parallactic angle from the first frame to the last, degrees.

GpuInfo

GPU availability.

Field Type Required Description
adapter string, may be null no Adapter description.
available boolean yes A GPU backend can be created (a software adapter counts).
software boolean yes The adapter is a software rasteriser.

GranulationSummary

Granulation statistics of the stack (helia measure, the quality report).

Field Type Required Description
arcsec_per_pixel number (float), may be null no Image scale, arcseconds per pixel (absent without a fitted limb).
cell_diameter_px number (float) yes Mean diameter of whole granules, pixels.
cell_pitch_px number (float) yes Mean spacing of granules, pixels.
cutoff_freq number (float), may be null no Diffraction cut-off D / lambda in cycles per pixel; needs aperture_mm and a fitted limb.
lines array of string yes The report in lines, as the command line prints it.
resolved_freq number (float) yes Highest frequency (cycles per pixel) above 1% of the peak power.
rms_contrast number (float) yes Standard deviation over mean of the flattened disc-centre region (a fraction, 0.04 is 4%).
rolloff_freq number (float) yes Spatial frequency (cycles per pixel) where the noise-subtracted power spectrum has fallen to 10% of its peak.

Health

Liveness probe.

Field Type Required Description
status string yes Always ok.

InspectRequest

POST /captures/inspect body.

Field Type Required Description
bayer string, may be null no auto (default), none, rggb, grbg, gbrg or bggr: see what an override would change.
bit_depth integer (int32), may be null no Bits per sample instead of the SER header's (1 to 16).
endian string, may be null no little or big, instead of the SER header flag.
flip_rows boolean no Read the rows bottom to top.
path string yes Capture path relative to the data root.
row_order string, may be null no Row order of FITS frames: auto (default), top-down or bottom-up.

JobConfig

The same knobs as helia stack.

Field Type Required Description
align string no 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, or limb. The choice and its confidence come back in summary.alignment. Default "auto".
align_channels boolean no With colour: "true", register red and blue to green (atmospheric dispersion). Default true. Default true.
ap_auto boolean no 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). Excludes ap_size; needs multipoint. What was chosen comes back in summary.auto_ap. Default false.
ap_passes integer (int32), may be null no Alignment point passes, 1 or 2. 2 stacks once and measures the points again against that stack. Default 1; needs multipoint.
ap_residual boolean no Measure the alignment points once more against the finished stack, for the residual figure of the report (ap-residual.png). Costs one more registration pass. Needs multipoint. Default false.
ap_size integer, may be null no Alignment point size in pixels (8 to 1024). Absent: chosen from the image size.
ap_smooth boolean no Replace alignment point shifts that disagree with their neighbours by the neighbours' median. Needs multipoint. Default false.
aperture_mm number (float), may be null no Telescope aperture in millimetres, for the diffraction cut-off in summary.granulation and for r0 in summary.seeing.
autocrop boolean no Crop the result to the solar disc plus autocrop_margin, FITS too. A capture without a clear disc is left uncropped; summary.crop is then absent. Default false.
autocrop_margin number (float), may be null no Margin of autocrop as a percentage of the disc radius, 0 to 200. Default 10.
backend BackendArg no Compute backend. Default "auto".
bayer string no auto, none, rggb, grbg, gbrg or bggr. auto trusts the file's header, but checks a SER file labelled mono for a hidden Bayer mosaic and debayers when it finds one. none treats the frames as mono whatever the header says; a pattern forces it. Default "auto".
bit_depth integer (int32), may be null no Bits per sample instead of the SER header's (1 to 8 read one byte per pixel, 9 to 16 two). SER only.
calibration CalibrationConfig or null no
channel ChannelArg or null no
colour string, may be null no Colour of the output: auto (the preset in force), mono, a preset id, or true. true is true colour from a raw colour camera: red, green and blue stacked on one alignment, channels aligned, white balanced, written as an RGB TIFF or PNG or a three-plane FITS cube; it needs a Bayer capture and excludes channel, invert and colour_strength. The other looks colour a .tif or .png from the mono stack, and FITS output is mono and unaltered for them. Absent: the preset's colours if one was given, else mono.
colour_strength number (float) no Mix of colour and grey, 0 to 1. Default 1.0.
date string, may be null no 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.
debayer DebayerArg no Demosaicing method. Default "mhc".
detect_overlay boolean no Look for burned-in text (a SharpCap timestamp) and mask it. Default true.
disc_mask boolean no Fit the limb and place alignment points on the disc only. Default true.
edits array of object no Further edits, applied in order after sharpen: objects with an op of unsharp, wavelet, deconvolve, denoise, levels, curve, crop, rotate, flip or resize and that operation's parameters (see the sharpening and adjustments page of the user guide). Unset parameters take their defaults. Default [].
endian string, may be null no Byte order of 16-bit samples instead of the SER header flag: little or big. SER only.
exclude array of Region no Rectangles to keep alignment and scoring off. They are filled in every frame from the sky around them, so no patch shows in the result. Burned-in timestamps are found automatically (see detect_overlay). Default [].
field_rotation FieldRotationConfig or null no
flatten string, may be null no Flatten the disc's limb darkening before anything else: model (divide by the fitted law) or profile (divide by the measured azimuthal median). Outside the limb nothing changes. It runs first, so sharpen and edits see flat contrast. A capture with no clear disc is left as it is and summary.limb_darkening is absent.
flip_rows boolean no Read the rows bottom to top. SER only. Default false.
grade string, may be null no Colour grading on top of the look: 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 and b channel curves 0.3 to 3). Absent: no grading. Not with colour: "true".
invert boolean no Invert before colouring (shows filaments and prominences). Default false.
keep string, may be null no Share ("25%") or count ("500") of frames to keep. Default 25%.
keep_frames integer, may be null no Number of frames to keep; excludes keep.
limb_law string, may be null no The limb-darkening law fitted to the stack and used by flatten: linear, quadratic (the default) or neckel (five terms). The fit comes back in summary.limb_darkening whether or not flatten is set.
metric MetricArg no Frame ranking metric. Default "gradient".
multipoint boolean no Multi-point alignment; false is global alignment only. Default true.
plugin_steps array of string no Steps of plugins to run, each PLUGIN/STEP, optionally followed by :KEY=VALUE,KEY=VALUE or :{"json":"object"} for its parameters and optionally preceded by pre: for an image step that runs before sharpen and edits. A frame-op step runs on every frame before it is scored; an image-op step on the stack (after sharpen and edits unless pre:); an analyse step on the result, and what it reports comes back in summary.plugins. The plugins must have been enabled on the server (helia plugins enable); a plugin that is off, changed or unknown, or a value outside the step's range, is a 422. They run with the rights of the server. At most 16. Default [].
preset string, may be null no Filter preset (ha, cak, cah, mg, na, he-d3, hbeta, white; see GET /presets): its channel and frame share apply wherever channel and keep are absent, and a .tif or .png output is coloured with it. Absent: the filter is detected from the file name, folder, sidecar or header, for the settings only.
prominence_band integer no Pixels outside the fitted limb where alignment points are still allowed; 0 keeps them on the disc. Default 0.
report boolean no Make the science report: the frame quality graphs (sorted and in capture order, with the keep threshold), the quality histogram, the global shift and drift and the seeing over the capture, as PNG with their data as CSV and JSON, and one self-contained HTML page. Turns the seeing probe on (about 120 more frames are read). The files are listed in summary.report; fetch them with GET /jobs/{id}/report and GET /jobs/{id}/report/{file}. Default false.
robust RobustArg or null no
robust_k number (float), may be null no Threshold of robust in standard deviations. Default 2.5 for sigma, 1.345 for huber, 2 for winsor.
row_order string, may be null no Row order of FITS frames: auto (default), top-down or bottom-up. auto follows a ROWORDER card, else Seestar S50 frames are top-down and all others bottom-up.
seeing boolean no Estimate the seeing from the capture (summary.seeing): the Fried parameter from the spectral ratio, which needs aperture_mm, and a relative alignment point motion index. Default false.
sharpen string, may be null no Sharpening of the stack: wavelet (Registax-style layers, the usual choice), unsharp, rl (Richardson-Lucy) or none, with the recommended values of the filter in force. Absent: none. It runs first, on the mono image, before edits and before any colour.
sharpen_fits boolean no Apply sharpen and edits to FITS output too. By default a FITS file is the unsharpened stack. Default false.
sigma_clip number (float), may be null no Sigma clipping threshold in standard deviations; off when absent. Same as robust: "sigma" with robust_k.
site string, may be null no Observing site as "lat,lon,alt" (degrees north, degrees east, metres), written to a FITS output as OBSGEO-X/Y/Z. Absent: the server's HELIA_SITE environment variable, else the keywords are left out.
stack_backend string, may be null no Stack with this stack-backend plugin instead of on the server's own pipeline. Not with report, true colour, calibration or field rotation.
sunspots SunspotsConfig or null no
wavelets string, may be null no Wavelets as in RegiStax 6, replacing the recommended layers: the registax: form of the CLI's --wavelets, for example registax:l1=100/0.14/0.2,l2=100/0.11/0.15,scheme=dyadic,filter=gaussian. A layer is amount/sharpen[/denoise] (amount 0 to 200 %, sharpen -0.1 to 1, denoise 0 to 1.5); the gain is 1 + amount * sharpen * \|sharpen\| (0.14 at 100 % is 3x, 1 is 101x) and the noise cut 10 * denoise * amount / 100 noise sigmas. Other keys: scheme (dyadic or linear), filter (default or gaussian), initial, step, linked (on). Implies sharpen: "wavelet"; with sharpen: "rl" the wavelets run after the deconvolution (the usual order: deconvolve, then lift and denoise); excludes unsharp.
white_balance string, may be null no White balance of colour: "true": auto (make the disc centre neutral), off (the sensor's own balance) or "R,G,B" gains such as "1.9,1,1.5". Default auto. Only with colour: "true".

JobEvent

Message on the /events WebSocket.

One of:

  • Full job view, sent once on connect. Fields: job (JobView), type = snapshot.
  • State change. Fields: error (ErrorBody or null), job (integer (int64)), state (JobState), type = state.
  • Progress tick. Fields: job (integer (int64)), progress (number (float)), stage_progress (number (float)), stage (string), type = progress.

JobRequest

POST /jobs body.

Field Type Required Description
config JobConfig no Stacking settings.
input string yes Capture path (.ser or .avi), relative to the data root.
output string yes Output path; .tif/.tiff or .fits/.fit/.fts.
overwrite boolean no Replace an existing output file.

JobState

Lifecycle state.

One of queued, running, succeeded, failed, cancelled.

JobSummary

What a finished stack contains.

Field Type Required Description
alignment AlignmentSummary yes How whole frames were aligned, and how confident that was.
alignment_points_active integer, may be null no Active alignment points (multi-point only).
alignment_points_total integer, may be null no Alignment points in the grid (multi-point only).
auto_ap AutoApSummary or null no
bayer string, may be null no Bayer pattern the frames were decoded with (rggb ...); absent for mono.
bayer_source string yes Where that came from: header, sidecar, detection or override.
calibration array of string yes The calibration masters applied, one line each, and any warning about them (a flat with rings, a dark that could not be scaled). Empty when the job had no calibration.
colour string, may be null no How the output was coloured, in words; absent for a mono output.
crop Region or null no
edited boolean yes The edits were applied to the pixels of the output.
edits array of string yes The edits recorded in the output file, one line each. For FITS output without sharpen_fits this is the note that the file is unedited.
field_rotation FieldRotationSummary or null no
filter string, may be null no Preset id in force (chosen or detected), if any.
filter_source string, may be null no Where the filter was read from (chosen, or the text it was found in).
frames integer yes Frames in the capture.
granulation GranulationSummary or null no
height integer yes Output height.
kept integer yes Frames in the kept set.
limb_darkening LimbSummary or null no
notices array of string yes Things worth knowing about how the capture was read, such as a Bayer mosaic found in a file whose header says mono.
plugins array of PluginSummary no What the analyse steps of plugins reported, with plugin_steps set.
registered integer yes Frames registered.
report ReportSummary or null no
seeing SeeingSummary or null no
sharpen_check SharpenCheckSummary or null no
stacked_by string, may be null no The stack-backend plugin that made the stack, with stack_backend set.
sunspots SunspotsSummary or null no
true_colour TrueColourSummary or null no
width integer yes Output width.

JobView

Public view of a job.

Field Type Required Description
backend string, may be null no Backend used.
config JobConfig yes The settings in force.
created_at integer (int64) yes Creation time, Unix milliseconds.
error ErrorBody or null no
finished_at integer (int64), may be null no End time, Unix milliseconds.
id integer (int64) yes Job id.
input string yes Input path relative to the data root.
output string yes Output path relative to the data root.
progress number (float) yes Approximate overall progress, 0 to 1.
queue_position integer, may be null no Position among queued jobs (0 is next), while queued.
run_seconds number (float), may be null no Seconds spent running so far or in total.
stage string, may be null no Current stage name, once running.
stage_progress number (float) yes Progress within the current stage, 0 to 1.
started_at integer (int64), may be null no Start time, Unix milliseconds.
state JobState yes State.
summary JobSummary or null no
timings array of StageTiming yes Per-stage wall times of a finished run.

LicenceDetails

Licensing of the software.

Field Type Required Description
copyright string yes Copyright line.
licence string yes SPDX licence identifier.
source string yes Source code location.

LimbSummary

A limb-darkening law fitted to the stack's azimuthal median profile.

Field Type Required Description
coefficients array of number (float) yes The coefficients, I(mu) / I(1) = 1 - sum c_k (1 - mu^k) for neckel, 1 - u (1 - mu) - u2 (1 - mu)^2 for the others.
law string yes linear, quadratic or neckel.
limb_level number (float) yes The law at the limb as a share of the disc centre.
names array of string yes Names of the coefficients, in order (u1, u2, or a1 to a5).
radius_px number (float) yes Fitted disc radius, pixels.
rms number (float) yes Root mean square departure of the profile from the law, as a share of the centre intensity.
text string yes The fit in a sentence.

Limits

Server limits.

Field Type Required Description
active_jobs integer yes Jobs queued or running now.
max_body_bytes integer yes Request body limit in bytes.
max_queue integer yes Queued plus running jobs allowed.
workers integer yes Concurrent jobs.

MetricArg

Sharpness metric.

One of gradient, laplacian, helmli, mfgs, dct, fourier, contrast.

MosaicPair

How a pair of panels matched.

Field Type Required Description
a integer yes First panel, from 1.
b integer yes Second panel, from 1.
ncc number (float) yes Normalised correlation of the detail on the overlap.
overlap_px integer yes Pixels shared.
residual_px number (double) yes How far the pair is from where the placement put it, pixels.
used boolean yes Whether it was used in the placement.

MosaicPanel

Where a panel went.

Field Type Required Description
angle_deg number (double) yes Rotation against the first panel, degrees (clockwise on screen).
derotated_px number (float), may be null no The most the derotation moved the surface of this panel, pixels, when it ran.
gain number (float) yes Gain applied for the brightness match.
input string yes The input.
offset number (float) yes Offset applied for the brightness match.
panel integer yes Position in inputs, from 1.
x number (double) yes Shift in the mosaic's coordinates, pixels (the first panel is at 0).
y number (double) yes Shift in y, pixels.

MosaicRequest

POST /mosaic body.

Field Type Required Description
derotate DerotateConfig or null no
feather_px number (float), may be null no Width of the blend across a seam and at a panel's edge, pixels (0 to 200, default 12).
gain_match boolean, may be null no Match the panels' gain and offset on the overlaps (default true).
inputs array of string yes Stacked panels (.tif, .tiff, .png, .fits) relative to the data root, 2 to 64. The first is the reference: the mosaic is in its orientation and brightness.
max_rotation_deg number (double), may be null no The most the panels may be turned against each other, degrees (0 to 45, default 4; 0 holds them square).
min_correlation number (float), may be null no Least normalised correlation of the detail on an overlap, 0 to 1 (default 0.45).
min_overlap_percent number (float), may be null no Least overlap that counts, percent of the smaller panel (default 5).
output string yes The mosaic to write, relative to the data root; the extension picks the format. The panel and pair tables are written beside it as NAME-panels.csv and NAME-pairs.csv.
overwrite boolean no Replace an existing output.
seams boolean, may be null no Join along seams of least difference (default true).
times array of string, may be null no UTC time of each panel, in the order given (needed for derotate). Without it a FITS file's DATE-AVG or a file name with a full date and time is used.

MosaicResponse

What a mosaic made.

Field Type Required Description
derotated_to string, may be null no The time the panels were brought to, UTC, when they were derotated.
disc array of number (double), may be null no The disc fitted to the mosaic: centre x, centre y, radius, pixels.
height integer yes Height of the mosaic.
notes array of string yes Plain-language lines about what happened.
output string yes The mosaic, relative to the data root.
overlap_rms number (float) yes RMS difference of the panels over the whole overlap, the same measure.
pairs array of MosaicPair yes The matched pairs.
pairs_table string yes The pair table (CSV), relative to the data root.
panels array of MosaicPanel yes The panels.
panels_table string yes The panel table (CSV), relative to the data root.
seam_rms number (float) yes RMS difference of the panels beside a seam, as a share of the level there.
width integer yes Width of the mosaic.

NoticeInfo

A message about how the capture was understood.

Field Type Required Description
level string yes info or warning.
text string yes The message.

PluginSummary

What one analyse step of a plugin reported.

Field Type Required Description
metrics object yes Named numbers.
notes array of string yes Lines of text.
overlays array of object yes Shapes in pixels of the output image, origin top-left: objects with a kind of circle, rect, line, points or text.
plugin string yes The plugin.
step string yes The step.

PresetColour

The colour parameters of a preset.

Field Type Required Description
exponents array of number (float) yes Per-channel exponent (red, green, blue).
gains array of number (float) yes Per-channel gain (red, green, blue).
gamma number (float) yes Tone exponent applied before colouring (below 1 brightens).
mid_grey_rgb array of integer (int32) yes What a mid-grey (0.5) becomes, 8-bit red, green, blue.

PresetList

GET /presets body.

Field Type Required Description
presets array of PresetView yes Every preset.

PresetSharpen

The recommended sharpening values of a preset (what sharpen in a job uses for this filter).

Field Type Required Description
denoise number (float) yes Wavelet denoise strength.
reason string yes Why they are what they are.
rl_iterations integer (int32) yes Richardson-Lucy iterations.
rl_tv number (float) yes Richardson-Lucy total-variation weight.
unsharp_amount number (float) yes Unsharp mask amount.
unsharp_threshold number (float) yes Unsharp mask threshold (image units, 0 to 1).
wavelet_gains array of number (float) yes Wavelet gain of layers 1 to 6.
wavelet_noise array of number (float) yes Wavelet noise threshold of layers 1 to 6, in noise sigmas.

PresetView

One filter preset.

Field Type Required Description
channel string yes Bayer channel stacked (r, g, b or lum).
colour PresetColour yes Colour parameters. Colour is presentation, not measurement.
hue string yes Hue in words.
id string yes Id to give as preset or colour in a job: ha, cak, ...
keep_percent number (float) yes Share of frames kept, percent.
name string yes Plain name.
reason string yes Why the recommendations are what they are.
sharpen PresetSharpen yes Recommended sharpening values.
summary string yes One line on what it is for.
wavelength string yes Wavelength as printed in the docs.

What Helia would do with a capture if given no settings.

Field Type Required Description
ap_size integer yes Alignment point size in pixels.
channel string yes Bayer channel it would stack (r, g, b, lum).
filter string, may be null no Preset id detected from the file name, folder, sidecar or SER header.
filter_source string, may be null no The text the filter was read from.
keep_percent number (float) yes Share of frames it would keep, percent.

Region

A rectangle of the frame, in pixels from the top-left corner.

Field Type Required Description
h integer yes Height; at least 1.
w integer yes Width; at least 1.
x integer yes Left edge.
y integer yes Top edge.

ReportSummary

The science report of a job.

Field Type Required Description
files array of string yes File names: report.html, the figures (*.png) and their data (*.csv, *.json). Fetch one with GET /jobs/{id}/report/{file}.
not_drawn array of string yes Figures that were not drawn, and why (for example, no seeing data).

RobustArg

Outlier-robust combination of the frames at each pixel.

One of none, sigma, huber, winsor.

SeeingSummary

Seeing estimated from the capture.

Field Type Required Description
d_over_r0 number (float), may be null no D / r0 from the spectral ratio; needs aperture_mm.
frames integer yes Frames followed (spread over the whole capture).
grade string, may be null no excellent, good, fair, poor or bad, from r0_500nm_cm.
lines array of string yes The report in lines, as the command line prints it.
motion_arcsec number (float), may be null no The same in arcseconds, with a fitted limb.
motion_px number (float), may be null no RMS differential motion between neighbouring alignment points, per axis, pixels. A relative index, not r0.
r0_500nm_cm number (float), may be null no Fried parameter at 500 nm, centimetres.
r0_cm number (float), may be null no Fried parameter at the capture's wavelength, centimetres.
tiles integer yes Tiles of the disc followed.

SerHeaderInfo

A SER header exactly as written in the file, decoded.

Field Type Required Description
colour_id integer (int32) yes ColorID as stored.
colour_meaning string yes Its meaning (MONO, BAYER_RGGB ...).
date_time string, may be null no DateTime (local) decoded; absent when unset.
date_time_utc string, may be null no DateTimeUTC decoded; absent when unset.
file_id string yes FileID.
frame_count integer (int32) yes Frame count.
height integer (int32) yes Height in pixels.
instrument string yes Instrument.
little_endian boolean yes LittleEndian flag as stored.
lu_id integer (int32) yes LuID.
observer string yes Observer.
pixel_depth integer (int32) yes Bits per sample.
telescope string yes Telescope.
timestamps TimestampInfo or null no
width integer (int32) yes Width in pixels.

SharpenCheckSummary

Did the sharpening add detail, or mostly noise (see the sharpening page of the user guide).

Field Type Required Description
detail_gain number (float) yes The 1 to 4 pixel band of the stack after the edits over before.
noise_gain number (float) yes The pixel-scale band after over before: the noise.
noise_level number (float) yes Noise level of the stack as a share of the mean.
residual number (float), may be null no Deconvolution residual as a share of the mean, when there was one.
verdict string yes fine, noise_dominated or overfit.
warning string, may be null no A sentence for a person, when the verdict is not fine.

SidecarInfo

SharpCap sidecar contents that Helia uses.

Field Type Required Description
bayer_hint string, may be null no Bayer pattern implied by the sidecar.
colour_space string, may be null no Colour Space value.
frame_count integer, may be null no Frame count from the sidecar.
path string yes Sidecar path relative to the data root.
raw_colour boolean, may be null no Whether the sidecar says the data is raw colour.
sections array of string yes Section headings (camera model).

SolarDerotationRequest

POST /solar-derotation body.

SolarDerotationResponse

What a solar derotation made.

Field Type Required Description
images array of DerotatedImage yes The images, in the order given.
target string yes The time every image was brought to, UTC.

SourcedFlag

A switch and where its setting came from.

Field Type Required Description
source string yes header, sidecar, detection or override.
value boolean yes The value.

SourcedNumber

A number Helia uses and where it came from.

Field Type Required Description
source string yes header, sidecar, detection or override.
value integer (int32) yes The value.

SourcedText

A value Helia uses and where it came from.

Field Type Required Description
source string yes header, sidecar, detection or override.
value string yes The value.

StageTiming

Wall time of one stage.

Field Type Required Description
seconds number (float) yes Seconds.
stage string yes Stage name.

SunspotGroupRow

One group of sunspots.

Field Type Required Description
area_msh number (float) yes Corrected, millionths of the hemisphere.
cmd_deg number (float) yes Area-weighted central meridian distance, degrees.
id integer yes Number from 1, largest first.
lat_deg number (float) yes Area-weighted latitude, degrees north.
lon_deg number (float), may be null no Area-weighted Carrington longitude, degrees (needs time).
projected_msh number (float) yes As seen, millionths of the visible hemisphere.
spots integer yes Spots in it.
umbra_msh number (float) yes Umbrae corrected, millionths of the hemisphere.
umbrae integer yes Umbrae in it.

SunspotRow

One sunspot.

Field Type Required Description
area_msh number (float) yes Corrected for foreshortening, millionths of the hemisphere.
cmd_deg number (float) yes Central meridian distance, degrees, west positive.
group integer yes Its group.
id integer yes Number from 1.
lat_deg number (float) yes Heliographic latitude, degrees north.
lon_deg number (float), may be null no Carrington longitude, degrees (needs time).
mu number (float) yes Cosine of the angle from disc centre.
penumbra_px integer yes Penumbra pixels.
projected_msh number (float) yes As seen, millionths of the visible hemisphere.
umbra_msh number (float) yes Umbra corrected, millionths of the hemisphere.
umbra_px integer yes Umbra pixels.
umbrae integer yes Umbrae in it.
x number (float) yes Centroid, pixels.
y number (float) yes Centroid, pixels, top row 0.

SunspotsConfig

Tuning of the sunspot detection; every field is optional.

Field Type Required Description
celestial_north_up boolean no The image has celestial north up: add the position angle P of the Sun at the capture time to north_angle_deg. Default false.
group_gap_deg number (float), may be null no Spots closer than this on the Sun, degrees, form one group. Default 3.
max_area number (float), may be null no Largest spot, millionths of the hemisphere; bigger dark regions are left out as a cloud or vignette. Default 6000.
min_area number (float), may be null no Smallest spot, millionths of the hemisphere. Default 2.
mirror boolean no The image is a mirror image. Default false.
north_angle_deg number (float), may be null no Counter-clockwise angle from the top of the image to solar north, degrees. Default 0.
penumbra number (float), may be null no Penumbra threshold, a share of the quiet disc (0 to 1). Default 0.88.
umbra number (float), may be null no Umbra threshold, a share of the quiet disc (0 to 1). Default 0.55.
wolf_k number (float), may be null no Observer factor k of the Wolf number. Default 1.

SunspotsSummary

Sunspots on the stack: counts, areas and the table.

Field Type Required Description
area_msh number (float) yes Everything corrected for foreshortening, millionths of the hemisphere.
b0_deg number (float), may be null no Heliographic latitude of the disc centre, degrees (needs time).
disc array of number (float) yes Disc centre x, centre y and radius the positions are measured on, pixels.
group_table array of SunspotGroupRow yes One row per group.
groups integer yes Sunspot groups, g.
k number (float) yes The observer factor used.
l0_deg number (float), may be null no Carrington longitude of the disc centre, degrees (needs time).
lines array of string yes The report in lines, as the command line prints it.
notes array of string yes Things to be careful about.
p_deg number (float), may be null no Position angle of the solar axis, degrees (needs time).
projected_msh number (float) yes Everything as seen, millionths of the visible hemisphere.
spot_table array of SunspotRow yes One row per spot.
spots integer yes Individual spots, s (umbrae and pores).
time string, may be null no Capture time used, ISO 8601 UTC; absent when the capture had none.
umbra_msh number (float) yes Umbrae corrected, millionths of the hemisphere.
wolf number (float) yes Relative Wolf number k (10 g + s).

TimelapseFrame

One frame of a finished time-lapse.

Field Type Required Description
derotated_px number (float), may be null no The most the derotation moved the surface of this frame, pixels, when it ran.
file string yes The frame file, relative to the data root.
frame integer yes Position in the sequence, from 1.
gain number (float) yes Gain applied for the brightness (1 without deflicker).
input string yes The input it came from.
limb_confidence number (float), may be null no Confidence of the frame's limb fit, 0 to 1, when it has one.
method string yes reference, limb, limb+phase, phase or failed.
phase_psr number (float), may be null no Peak-to-sidelobe ratio of the phase correlation, when it ran.
shift_x number (float) yes Shift applied, pixels (the frame's content was at the reference plus this).
shift_y number (float) yes Shift applied, pixels.
time string, may be null no Capture time, UTC, when known.

TimelapseRequest

POST /timelapse body.

Field Type Required Description
crop boolean no Cut every frame to the area all of them cover.
deflicker string, may be null no off (default), match or smooth.
deflicker_window integer, may be null no Frames in the running median of smooth (odd, at least 3; default 5).
derotate DerotateConfig or null no
format string, may be null no Frame format: png (8-bit, default) or tiff (16-bit).
fps number (float), may be null no Frames a second of the movie (default 10, up to 120).
inputs array of string yes Stacked images, relative to the data root, one per frame (2 to 200). They are put in time order when every one has a time.
max_refine_px number (float), may be null no Largest correction in pixels the refinement may make (default 3).
movie string, may be null no auto (default: MP4 when ffmpeg is installed, else an animated PNG), mp4, apng or none.
output string yes Directory for the frames, the movie and the table, relative to the data root. Created when missing.
overwrite boolean no Replace an earlier time-lapse in output.
reference string, may be null no The frame the others are registered to: first, middle (default) or a number counting from 1.
refine boolean, may be null no Refine the limb shift by phase correlation of the disc centre (default true).
report boolean no Also write the diagnostics of the series into output/report/: how each frame was registered, the brightness before and after deflicker, and the derotation displacement, as PNG, CSV and JSON and one self-contained report.html (summary report).
times array of string, may be null no UTC capture time of each input (YYYY-MM-DDThh:mm:ss), in the order given in inputs. Without it a FITS file's DATE-AVG or a file name that holds a full date and time is used; frames with no time are kept in the order given.

TimelapseResponse

What a time-lapse made.

Field Type Required Description
crop Region or null no
frames array of TimelapseFrame yes The frames in order.
height integer yes Height of the written frames.
movie string, may be null no The movie file, relative to the data root, when one was made.
movie_kind string, may be null no mp4 or apng.
notes array of string yes Plain-language lines: what registration did, and any caveat.
reference integer yes The reference frame, from 1.
report string, may be null no The diagnostics page (report.html), relative to the data root, with report; its figures and data are beside it.
table string yes The registration table (CSV), relative to the data root.
width integer yes Width of the written frames.

TimestampInfo

SER trailer timestamps.

Field Type Required Description
count integer yes How many.
first string, may be null no First, UTC.
last string, may be null no Last, UTC.

TrueColourSummary

What a true-colour job did.

Field Type Required Description
channels array of ChannelSummary, may be null no Red and blue against green; absent when align_channels was off.
gains array of number (float) yes Gains applied to red, green and blue, including the common scale that keeps the picture inside white.
notes array of string yes The notes written into the file's history, including warnings (a channel held at the largest automatic gain, a shift not applied).

VersionInfo

/version response.

Field Type Required Description
api string yes API version in the URL prefix.
auth_required boolean yes Whether a token is required.
backends Backends yes Backends.
build BuildDetails yes Build record.
licence LicenceDetails yes Copyright and licence.
limits Limits yes Limits.
name string yes Package name.
version string yes Package version.