# Kombine

Kombine collects multiple frames to create a new enhanced image.

## Command

`munipack kombine [..] files`

## Description

Purpose of this routine is

- to collect observed frames together,
- to reveal very faint objects (potentially invisible on a particular frame),
- to increase of the dynamic range of frames,
- to average frames, or
- to create of a mosaics covering larger sky area than any single frame.

The image can be scaled to arbitrary size, rotated, shifted and reflected. The routine provides sub-pixel resolution. The blurring of image due to convolution can be reduced by a local interpolation method.

The output frames can be used for a regular photometry. To keep proper both surface photometry and sky (background), the switch `--disable-back` should be presented. By default, the background is removed during the composition process.

The intensity-like values in the output images represents the sum of ones, notwithstanding the values are computed by averadging.

## The algorithm

1. Kombine had started the processing by developing of a grid, in spherical coordinates, which covers desired area.
2. Every input frame is re-projected on the sky grid:

1. The coordinates of the pixels are interpolated, and
2. their values are averaged.

3. The output frame is a projection of the sky grid nodes onto plane of the new synthetic image.

## Input and output

On input, list of frames with astrometry calibration is necessary. A regular photometry calibration is recommended for averaging.

On output, the mean of the input files is created. The file has STDERR extension with standard errors. The MAXDEV extension contains maximal deviations of the robust mean (not included if `--arith`); it helps to detect anomalies.

## Memory space requirements

Kombine requires approximately NAXIS(1)*NAXIS(2)*4 bytes per frame (frames are stored as single precision real numbers). For an illustration, one hundredth of 1000 × 1000 frames (1MB) takes 400 MB in memory.

## Parameters

### Parameters for composition:

`-i, --interpol [near,bilinear,bicubic,bi3conv]`
  An interpolation method selection: nearest neighbourhood, bilinear, bicubic, and bi3conv by convolution.

  The bi-cubic interpolation gives smooth, little bit sharpen, images. The convolution variant of bi-cubic interpolation gives better results for critically under-sampled frames. Warning: All bi-algorithms can create an artificial fingering patterns on the background.

  By default, the nearest neighbourhood method is used. It is also the fastest method. For under-sampled data, one brings a little bit pixelised images.

`--disable-back`
  switch-off the subtracting of a estimated background. The frames has the actual background unchanged, preserving the sky brightness. It is intended for the astronomical photometry. Final frames, especially a mosaics, can contains unfolded regions with brighter and fainter backgrounds.
`--arith`
  Kombine computes the average by arithmetic mean per every single pixel. By default, the average is computed by robust mean, giving the brilliant look of results, yet both significantly slower and memory consuming.

### Projection parameters:

`-p, --projection [none, gnomonic]`
  projection: none, gnomonic (default)
`--rcen ddd.ddd, --dcen ddd.ddd`
  centre of projection in Right Ascension and Declination [deg]
`--pm-ra d.ddd, --pm-dec d.ddd`
  proper motion of centre of projection in [deg/day]
`--pm-jdref JD`
  reference Julian date for the proper motion
`--width xxx, --height yyy`
  dimensions of the output frame in pixels
`--xcen xxx.x, --ycen yyy.y`
  centre of projection on result [pix] (default: width/2, height/2)
`--scale sss.sss`
  scale [deg/pix]
`--angle ddd.ddd`
  rotation angle [deg]
`--reflex [yes|no]`
  setup reflection

Any unspecified parameters are inherited from the first frame on input. The strategy is chosen to be the minimal surprise way.

The life will be easy by setting of the output frame with the zero rotation angle (`--angle 0`), as well as without any reflection (`--reflex no`).

See Common options for input/output filenames.

## Examples

The very basic, and common way, of use is

`$ munipack kombine images*.fits`

All parameters of output frame (saved to `kombine.fits`) are inherited from the first frame.

Other common usage specifies the output filename, and adjust orientation by spherical grid:

`$ munipack kombine -o kombi.fits --angle 0 --reflex no images*.fits`

The frames can be composed into a large canvas (1000×1000 pixels) and scaled by factor two. As the first step, one determines the frame scale by FITS keywords

    $ munipack fits -K CD1_1,CD1_2 image1.fits
    CD1_1   = -2.6589961865059603E-04
    CD1_2   = -6.0182917772180531E-06

The frame scale is √({CD1_1}2 + {CD1_2}2) = 2.66e-4 deg/pix. The parameters are

`$ munipack kombine --width 1000 --height 1000 --scale 5.32e-4 images*.fits`

A little bit uncommon example describes the tracking of comets or faint asteroids:

`$ munipack kombine --pm-ra 0.4 --pm-dec -0.01 images*.fits`

The utility sets initial frame position and time by the first image and shifts all next images by the specified proper motion. Best way how to get values of the proper motion is to use of its ephemeris. An alternative, for visible objects, is the difference of object coordinates between the first and last images.

A demonstration of interpolation methods. The frames has been created by:

    $ munipack kombine            -o m86.fits     m86_V_*_proc.fits
    $ munipack kombine -i bicubic -o m86_bic.fits m86_V_*_proc.fits
    $ fitspng -s 3 -r 0.3,30 m86.fits
    $ fitspng -s 3 -r 0.3,30 m86_bic.fits

The picture of neighbourhood of M 86 as a demonstration of nearest neighbourhood interpolation method. The image series is an composition of 52 observed images. The observation has included the meridian flip. The after-flip images are with an offset. The offset can be distinguished on a large rectangular region having slightly different background at the top-right part of the composition.
The same composition with bi-cubic interpolation applied. The fringing patterns are clearly visible in the after-flip region having offset.

## See Also

Frame composition is the detailed tutorial how to made of a deep exposure; Mosaics describes assembly of a mosaic. Frame colouring uses `kombine` to get deeper frames (nice example of the application of `--rcen, --dcen` parameters).

See also: Slip, Common options