# Colour frame composition

Colouring utility for composing of frames in natural colours.

## Command

`munipack coloring [options] [file(s)] ...`

## Description

Munipack implements a method which transforms images taken via a set of standard photometric filters (Johnson BVR or an equivalent) to CIE 1931 XYZ colour space ― sensitivity of the human eye. Main purpose of the utility is to offer possibility to create images in natural colours from instrument not equipped by CIE 1931 XYZ filters (eg. any astromical telescope). Results has colours near of natural colours and simulates how the object would be seen by an extraordinary observer, like a huge digital camera.

## Calibrated results

If the input frames are calibrated, or ctph is specified, the output colour frames has absolute calibration in intensities (energy carried by photon rates). To partialy preserve values, the frames are keeped in energy rates in electronvolts per second, square meter and square arcseconds (rather than W/m2/srad as SI reccomends).

There are important difference between common digital detectors (CCD, cameras) and human eye: the human eye detect energy, whilst these are photon detectors.

## RGB colour space

CIE 1931 XYZ has been selected as the default output colour space due compatibility with dcraw. Also, the colour space is very near to Johnson giving more accurate transformation matrix. Much more, CIE 1931 XYZ is ideal for additional processing due wide common CIE Luv, CIE Lab.

In contsrast, sRGB or Adobe RGB are very specific spaces, non-linear and very difficlout to modify. They are considered as final product, whilst CIE 1931 XYZ are intended for additional tunning.

## Input and output

On input, a list of frames is expected. The frames should be specified in short wavelengths first order (conventional BVR order) on command line, this is oppposite to RGB (XYZ). The filters in headers should be specified exactly as B, V, R characters for Johnson's system, no aliases are allowed.

On output, the colour frame in Colour FITS is created.

## Parameters

`-c, --cspace-input colour-space`
  Specify the colour-space of input images (eg. 'Johnson BVR'). If the value is not given, passed frames are scaned for filters, and the colour space is guessted from them.
`--cspace-output colour-space`
  Specify the final colour space identification. 'CIE 1931 XYZ' is used by default. Anotehr possible value is 'Johnson BVR' which can be usefull for additional processing, like tunning in xmunipack.
`-w, --weights w1,w2,...`
  Gives weights of particular colour bands. There are no limitation on weights except: all of them must be possitive numbers, their count must corresponds to passed input frames.
`-q, --ctphs ctph1,ctph2,...`
  Gives reciprocal quantum efficiency for particular colour bands. The values can be determined by photon calibration. Generally, it is proper characteristics of given aparatus (detector, filters and telescope), but slighly varies with observing conditions.
`-b, --backs back1,back2,...`
  Gives background levels of particular colour bands on input frames. By default, medians of image levels are used. It is very good star point for fine tune, in case of astronomical frames.
`--disable-back`
  Disables estimation of backgrounds levels. It is helful for non-astronomical frames.
`--white-spot x,y`
  Specifies coordinates in pixels of a spot of circular shape with a radius (default 7 pixels). The spot is a white part of frame, robust mean in particular filters is used to determine weights.
`--white-star x,y`
  Specifies coordinates in pixels of a star considered as a white star (stars with temperatures 10 thusands kelvins, with B-V = 0 or spectral class A0). An aperture of circular shape with a radius (default 7 pixels) is used to determine the total flux in particular filters and to determine of weights. This option is there mainly to give a prove that it works, calibrated frames gives better results and are easy to use.
`--white-radius r`
  Specifies radius of the aperture (for star) or the spot for determination of white colour. By default, it is 7 pixels.
`--list`
  Prints a table with available colour space transformations.

See Common options for input/output filenames.

## Examples

Create a new color FITS image `m27.fits` from a set of files taken with filters `m27_[B,V,R].fits`:

    $ munipack colouring -o m27.fits m27_B.fits m27_V.fits m27_R.fits

Dumbbell nebula in natural colours

## See Also

Colour Processing, Common options