Stacking

Stacking operates on a set of input files to produce a monochrome output stack in linear light. Basic invocation is nightlight -out channel.fits stack subexposures*.fits, with suitable naming for the subexposures from your camera, and the desired output filename.

If there is enough main memory, nightlight processes all frames in one large batch. Otherwise, the list of input files is split into random batches of the largest size that will fit into memory. Use -stMemory 8000 to e.g. assign 8000 MiB of memory for stacking.

The pipeline for stacking has four main phases: 1. preprocessing, 2. reference frame selection, 3. postprocessing and 4. stacking.

1. Preprocessing

Preprocessing operates on a batch of files in parallel. It encompasses:

• Load file. Currently limited to FITS image format
• Subtract master dark if given via -dark filename.fits
• Divide by master flat if given via -flat filename.fits
• Extract a single color channel, if this is a color filter array (CFA) file from a one-shot color (OSC) camera. Via -cfa RGGB -debayer R, using the color filter array value for your camera and the desired channel to extract. If you don't know the right CFA value, try all four options RGGB, GRBG, GBRG and BGGR until you find the right one. Wrong choices tend to produce identical histograms for two color channels, or wildly unrealistic colors.
• Cosmetic correction of bad pixels which are more than N standard deviations, also called sigmas, away from the local median. Via -bpSigLow 3.0 -bpSigHigh 5.0. Pick the values which work for your camera. Nightlight will show which share of pixels is clipped low and high by this. Typically, you should aim for 0.1% or less. This setting should remain reasonably stable for your camera.
• Optional NxN binning, via -binning 2 for 2x2 and so on.
• Histogram peak location and scale detection (for normalization later). Location and scale estimation methods can be selected via -lsEst N, where 0=mean/stddev, 1=median/MAD, 2=IKSS, 3=iterative sigma-clipped sampled median and sampled Qn (standard)
• Star detection and half-flux radius calculation (for image alignment later). You can parametrize the threshold pixel value for detecting stars via -starSig 10.0, providing the desired number of sigmas. Bad pixels can be filtered out here via -starBpSig 5.0 vs. the local median, this is fast even if you choose not to run global cosmetic correction. Finally, you can set the radius of stars to consider with -starRadius 16 giving the desired radius in pixels. You can save the star detection masks with a filename pattern like -stars stars%04d.fits.
• Background extraction. Set the desired grid spacing in pixels via -backGrid 128. Detected stars are automatically masked out. You can save the generated masks for inspection by providing a filename pattern like -back back%04d.fits.
• You can optionally store the results of Preprocessing by providing a filename pattern like -pre pre%04d.fits, which will save to pre0000.fits, pre0001.fits and so on.

2. Reference frame selection

This is a global step. Nightlight picks the frame with the highest quotient of number of stars divided by average half-full radius (HFR).

3. Post-processing

Post-processing again works on batches of files in parallel.

• Histogram normalization to the reference frame. You can select which kind of normalization happens with -normHist 3, where 0=do not normalize, 1=location and scale, 2=black point shift for RGB align, 3=auto
• Image alignment to the reference frame, also called registration. Result is two linear equations transforming image to reference frame coordinates. Enable with -align 1, disable with -align 0. You can choose how many of the brightest stars to use for initial alignment, say 20 via -alignK 20. You can also set an error threshold above which alignments (and frames) are discarded, via -alignT 1.0.
• Image projection to the reference frame. This uses the equation from alignment to project all pixels with bilinear interpolation
• Results can again be stored to disk with a filename patter like -post post%04d.fits

4. Stacking

• Choice of algorithm
• Choice of weights.
• Results are written to out.fits, or whatever is given via -out result.fits
• The stacks for each batch are incrementally combined with weighted mean stacking, using the number of frames in each batch as the weight.