Skip to content

Calibration

Jump to bottom
István Kovács edited this page Apr 3, 2025 · 3 revisions

Calibration of images

The calibration of images is performed using the ppl-calibration command.

Command-Line Options

You can view the available command-line switches with the ppl-calibration --help command.

ppl-calibration, version 1.2.0
Calibrate a set of RAW or FITS images.

Usage: ppl-calibration [OPTIONS]... [BASE_FOLDER]
Make calibration process for raw or FITS images.

Mandatory arguments to long options are mandatory for short options too.
  -c,  --color arg                Set filter(s), where arg is the color code; the default color is 'Gi'. 
                                  See below for available color codes.
  -n,  --count-combine n          Set the number of frames to combine in the sequence. 
                                  0 means all frames (default is 0).
  -f,  --flat                     Generate master flat frame only.
  -F,  --save-flat                Save master flat into the flat library.
  -m,  --master-flat folder       Use the specified master-flat folder.
  -M,  --use-flat                 Use a master flat from the flat library.
  -t,  --image-time LT|UT         Specify the original image time zone: 
                                  LT = Local Time, UT = Universal Time.
       --calib-folder folder      Specify an alternative folder for calibration frames (bias, dark, flat).
  -w,  --overwrite                Force overwrite of existing results.
  -e,  --on-error noop|skip|stop  Specify error handling behavior: 
                                  noop = ignore errors; skip = exclude the file from further processing; 
                                  stop = halt processing.
  -h,  --help                     Display this help message.

Available filter color codes are:
  Gi | G | gi | g         green channel
  Bi | B | bi | b         blue channel
  Ri | R | ri | r         red channel
  all | ALL | All         all channels, resulting in 3 separate frames.

If images are distributed across multiple directories (e.g., separated into different Light folders for each object), you can specify these directories using the BASE_FOLDER parameter. The program will search all directories that include this value in their name.

Explanation of Command-Line Options:

  • -c / --color <color>
    Specifies the color channel for processing. If set to all, all three channels will be processed. The default is all.

  • -n / --count-combine <n>
    Defines how many images to combine during time-series processing. For instance, dividing all images by the count value results in multiple combined images. By default, all images are combined.

  • -f / --flat
    Use this option to generate only flat frames (e.g., for archived flat frames).

  • -F / --save-flat
    Saves the master flat frame to the flat library.

  • -m / --master-flat <master-flat-directory>
    Specifies the directory containing archived master flat frames.

  • -M / --use-flat
    Searches for a suitable master flat frame in the flat library.

  • -t / --image-time <timezone>
    Specifies whether the timestamps in the raw images are in Universal Time (UT) or Local Time (LT, default).

  • --calib-folder <calibration-folder>
    Specifies an alternative folder for calibration frames (bias, dark, flat).

  • -w / --overwrite
    Forces the program to regenerate master frames, even if they already exist.

  • -e / --on-error <action>
    Defines error handling behavior during calibration:

    • noop (default): Ignore errors.
    • skip: Exclude the problematic file from further processing.
    • stop: Halt the entire calibration process.

  • -h / --help
    Displays help information and version details.

How ppl-calibration Works

The program follows these steps during the calibration process:

  1. Format Conversion
    If raw images are in vendor specific format (.CR2, .CR3, etc.), they are converted to .FITS format, which includes only one color channel. The -c option specifies which channel to use. If set to all, separate .FITS files for each channel are created, with filenames including the channel identifier.

  2. Master Frame Generation
    The program skips steps where the target master frame (e.g., master dark) already exists unless the -w option is specified to overwrite them.

  3. Calibration

    • Generates master bias, master dark, and master flat frames from their respective directories.
    • Applies these master frames to images in the Light directory, creating calibrated images in the Calibrated directory with the same names as the originals.

  4. Registration and Stacking

    • Registers calibrated images using the first image as the reference.
    • Stacks the registered images. The stacking behavior depends on the -n parameter:
      • If 0 (default), all images are stacked into a single file named Combined.
      • If N, images are stacked in groups of N (useful for time-series images), saved as Seq-n.

Master Flat Archive

If no flat images are available for a specific observation, archived master flats can be used. These are stored in the ~/.pmlib/flat directory, with filenames following this convention:
master-flat-<color>-<camera>-<instrument>-<date>.fits
Where:

  • color = Color channel (e.g., Gi, Bi, Ri).
  • camera = Camera name from the raw FITS files.
  • instrument = Instrument name from the FITS headers or configuration file.
  • date = Master flat creation date (format: YYYYMMDD).

Example: master-flat-Gi-EOS1100-250T-20200101.fits

When using the -M option, the program searches the flat library for a master flat matching the camera and instrument in the FITS files, created closest in time to the calibration.

Supported RAW File Types

While pmutil is theoretically compatible with all RAW file types supported by the LibRaw library, practical use is limited to tested formats:

  • CR2: Canon CR2 format for cameras manufactured between 2005–2018.
  • CR3: Canon CR3 format for cameras manufactured after 2018.

Handling Bad Images

If some of our images are bad (e.g., due to motion blur or overexposure), they can typically be deleted from the Light images.

However, when capturing a time-series image sequence (using the --count-combine option), deleting images is not a good solution. Removing images would cause a misalignment in the sequence, leading to time slices of unequal lengths.

To prevent this, individual Light images can be marked as faulty by adding the _bad suffix to their filenames. For example, Light_nnn.cr2 can be renamed to Light_nnn_bad.cr2. This way, the image will still be counted in the sequence, but it will not be included in the combined image for that time slice. This ensures that the time slice length remains consistent, at the cost of a slight increase in measurement error.

Similarly, the ppl-calibration command can automatically mark an image as faulty if its registration fails before summation. In this case, the _bad suffix is applied not to the original Light image but to the calibrated version of the image.

Clone this wiki locally