IntroductionPixInsight 1.7 introduces a new feature that may have passed unnoticed for many users:
format hints. Format hints are special parameters that you can pass to file format support modules to override global settings for specific file formats. The necessity to override format settings in PixInsight has arisen a number of times during the last year and a half, especially in software development contexts, and also more recently at the user level; an example is
this forum thread, where I devised the concept of format hints clearly for the first time.
ExamplesThe usefulness of format hints is better understood through examples. The ImageCalibration tool provides a good one. So far when ImageCalibration loaded DSLR raw frames, the current settings available in the
RAW Format Preferences dialog of the DSLR_RAW module (available from the Format Explorer window) always applied. If you wanted to load your family photos in PixInsight, you had to change DSLR_RAW settings to select an appropriate debayering interpolation algorithm and enable camera white balance. Later, to calibrate a set of astronomical images you had to remember changing DSLR_RAW settings again to disable debayering, white balance, black point correction, etc., in order to load pure raw data. This no longer happens in PixInsight 1.7, thanks to format hints.
Several processes allow you to specify format hints directly: ImageCalibration, StarAlignment, ImageIntegration and HDRComposition.
Input hints apply to image read operations, while
output hints apply to generation of new image files. Only ImageCalibration and StarAlignment allow you to specify output hints, since the other processes cannot write image files.
Let's put a more practical example. To solve the problem I have described above with ImageCalibration (family photos), you can specify the following input hint on the ImageCalibration tool:
rawThe
raw hint tells the DSLR_RAW module to load pure raw data, irrespective of the current DSLR raw format settings. Specifying the
raw hint forces the DSLR_RAW module to override its current settings with the following set:
Color adjustment: all three scaling factors = 1.0
Interpolation: none
Auto white balance: disabled
Camera white balance: disabled
Create RAW Bayer image: enabled
Black point correction: disabled
So if you specify the
raw input hint, ImageCalibration will load pure raw RGB Bayer images for DSLR raw input frames in a predictable way. If you want to load CFA monochrome images instead of RGB, you can also specify the
cfa hint. So your input hints would be in this case:
raw cfaMore examples. Let's say you want to calibrate a set of FITS files acquired with an amateur package that stores FITS images using the typical top-to-bottom, left-to-right orientation (TBLR). As you know, PixInsight uses the bottom-to-top, left-to-right orientation (BTLR) by default. You can override this setting and define an ImageCalibration instance that loads FITS files using the TBLR convention always, irrespective of the current FITS format settings. To achieve this you just have to specify the following input hint:
up-bottomIn this way ImageCalibration will load your raw FITS files with the correct orientation. It will write the calibrated frames using the current orientation set in FITS preferences unless you repeat
up-bottom as an output hint.
Continuing with FITS format issues, as you probably know floating point FITS files are the cause of a good amount of problems, mainly due to the lack of standardization characteristic of the FITS format, and particularly because FITS provides no way to specify the numerical range to which floating point data are referred (black and white points). Many image acquisition programs and some astronomical image manipulation applications write 32-bit floating point images in the range [0.0,65535.0], that is, a real range bounded as the 16-bit unsigned integer range. PixInsight, on the other hand, uses the [0,1] range for floating point image data by default, where 0=black and 1=white. Now you can force ImageCalibration to load floating point FITS files generated by other applications in the 16-bit range, using the TBLR orientation, with the following hints:
up-bottom lower-range 0 upper-range 65535Again, the above hints will allow you to correctly interpret FITS files generated by other applications, without the need to alter global FITS settings. Note that
lower-range and
upper-range can only be used as input hints; PixInsight will always write floating point images in the [0,1] range.
Format Hints ReferenceHere is a list of all input and output hints available in the standard file format support modules, as of PixInsight 1.7.0.697:
DSLR RAW FormatInput hintsrawEquivalent to:
bayer-drizzle no-cfa no-auto-white-balance no-camera-white-balance no-black-point-correctionbilinearEnables the bilinear debayering interpolation algorithm.
vngEnables the VNG debayering interpolation algorithm.
ppgEnables the PPG debayering interpolation algorithm.
ahdEnables the AHD debayering interpolation algorithm.
interpolate-as-4-colorsEnables the four-color interpolation option.
no-interpolate-as-4-colorsDisables the four-color interpolation option.
auto-white-balanceEnables automatic white balance.
no-auto-white-balanceDisables automatic white balance.
camera-white-balanceEnables camera white balance.
no-camera-white-balanceDisables camera white balance.
super-pixelsEnables super pixel debayering.
no-super-pixelsDisables super pixel debayering.
bayer-drizzleEnables loading of RGB raw Bayer images.
no-bayer-drizzleDisables loading of RGB raw Bayer images.
cfaEnables loading of monochrome raw CFA (color filter array) images.
no-cfaDisables loading of monochrome raw CFA images.
black-point-correctionEnables black point correction.
no-black-point-correctionDisables black point correction.
FITS FormatInput hintslower-range <real-number>Specifies the lower bound of the input range for floating point FITS images.
upper-range <real-number>Specifies the upper bound of the input range for floating point FITS images.
rescaleSpecifies that input images with out-of-range pixel values will be rescaled to the current floating point input range (no data loss).
truncateSpecifies that input images with out-of-range pixel values will be truncated to the current floating point input range (possible data loss).
bottom-upSelects the bottom-to-top, left-to-right FITS coordinate origin and orientation.
up-bottomSelects the top-to-bottom, left-to-right FITS coordinate origin and orientation.
signed-is-physicalSpecifies that signed integer FITS images store physical CCD raw values. In these images, the negative half of the available numerical range is not used. Pixel values range from 0 to 2
n-1-1, where n is the bit depth.
signed-is-logicalSpecifies that signed integer FITS images store logical values. In these images, the entire available numerical range is used. Pixel values range from -2
n-1 to +2
n-1-1, where n is the bit depth.
Output hintsunsignedWrites an unsigned integer FITS image (if an integer image is being generated).
signedWrites a signed integer FITS image (if an integer image is being generated).
bottom-upWrites a FITS image with the bottom-to-top, left-to-right FITS coordinate origin and orientation.
up-bottomWrites a FITS image with the top-to-bottom, left-to-right FITS coordinate origin and orientation.
TIFF FormatInput hintslower-range <real-number>Specifies the lower bound of the input range for floating point TIFF images.
upper-range <real-number>Specifies the upper bound of the input range for floating point TIFF images.
rescaleSpecifies that input images with out-of-range pixel values will be rescaled to the current floating point input range (no data loss).
truncateSpecifies that input images with out-of-range pixel values will be truncated to the current floating point input range (possible data loss).
Output hintszip-compressionWrites a TIFF file using ZIP (deflate) compression.
lzw-compressionWrites a TIFF file using the LZW compression algorithm.
uncompressedWrites an uncompressed TIFF file.
no-compressionSame as
uncompressedplanarWrites a planar TIFF file (in a planar TIFF image, each color channel of the image is stored as an independent matrix of pixel components).
chunkyWrites a
chunky TIFF file (in a chunky TIFF image, all color channels are written interlaced as a single block of data).
no-planarSame as
chunky.
associated-alphaThe alpha channel represents the opacity of the image.
no-associated-alphaThe alpha channel is an independent data set that does not represent the opacity of the image.
premultiplied-alphaColor pixel components are stored premultiplied by the alpha component.
no-premultiplied-alphaColor pixel components are stored unmodified.
JPEG FormatOutput hintsquality <integer-number>Specifies a quality factor in the range [0,100].
optimizedEnables optimized entropy coding.
no-optimizedDisables optimized entropy coding.
arithmeticSelects the arithmetic entropy coding algorithm (currently unsupported by the standard JPEG file format module).
huffmanSelects the Huffman entropy coding algorithm.
progressiveCreate a JPEG image that can be loaded by successive layers of increasing resolution.
no-progressiveDo not create a progrssive JPEG image.
