bitcount: Accumulate the bit statistics for a list of images

Package: obsutil

Usage

bitcount images

Parameters

images: A list of image names whose bit statistics will be counted. The statistics can either be reported for each individual image (the default) or as a grand total over all the images.

grandtotal = no: If grandtotal = yes, accumulate a grand total over all the images. If grandtotal = no (the default), report the statistics individually for each image in turn.

leftzeroes = yes: If leftzeroes = yes, leftmost zeroes are counted into the statistics (the default). If leftzeroes = no, leftmost zeroes (those past the most significant digit for each individual pixel) are omitted from the statistics.

verbose = yes: If verbose = no, only the raw bit counts will be reported.

Description

Bitcount will report the absolute and relative proportions of zeroes and ones populating each bit plane of a list of images. This is useful for diagnosing problems with a CCD's A/D converter, especially when an input image is supplied that contains a linear ramp in exposure across the range of the A/D.

The statistics for the list of images can be accumulated either individually for each image, or as a grand total over all of the images depending on the value of the grandtotal parameter. A single linear exposure ramp can be mimiced by a grand total over a list of progressively more exposed images. Care should be taken to arrange that the exposures sample all parts of the A/D's range.

The leftzeroes parameter is used to correct a problem seen with the ctio.bitstat task. Bitstat under-reports zeroes for the more significant bits since only pixels with values greater than the bit being currently counted participate in that count. The severity and precise nature of this problem depends on the exposure level of a particular test image. Leftzeroes may be set to "no" if there is some reason to restore this behavior.

The verbose parameter may be set to "no" in order to pass the raw bit counts on to some other task.

Examples

To report the bit statistics for a test exposure ramp:

nl> bitcount testramp

To accumulate a grand total over a list of images:

nl> bitcount a001*.imh grandtotal+

Bugs

A warning will be issued when accumulating a grand total over a list of images whose datatypes vary. In this case, the totals for each bit will be correct - to the extent that some images may not populate some bits - but the datatype of the final image in the list will control the range of bitplanes included in the output report. The interpretation of the most significant bit as a sign bit will also depend on the datatype of this final image.