HiRISE

HiRISE.HiPlan.HOGG
Class CCD_Histogram

java.lang.Object
  extended by HiRISE.HiPlan.HOGG.CCD_Histogram
All Implemented Interfaces:
Function2D

public class CCD_Histogram
extends Object
implements Function2D

A histogram for a single HiRISE CCD image. The histogram tabulates the number of pixels in the CCD image for each of the 16,384 possible 14-bit data values. The 14-bit data value is a response by the CCD to an input signal measured in electron counts. Each CCD responds differently to the same input signal.

The CCD response, DN14, in 14-bit data number to input signal in electron count is determined by an offset and a gain. In practice, the HiRISE calibration team measures inverse gain rather than gain, but the conversion is trivial.

A CCD_Histogram has a set of source_data, which are the 14-bit counts for a particular source CCD. The source CCD is described by a source_offset and source_inverse_gain.

The same data can be used to represent a different target CCD through the use of a target_offset and target_inverse_gain. Doing so only makes sense if one can assume that the same electron signal distribution is applied to the target CCD that was applied to the source CCD. This assumption is reasonable for HIPHOP modeling of CCDs with the same color filters; it is not reasonable for CCDs of differing color filters or for real Martian scenes. Consider, for example, the case in which the rightmost red CCD, RED0, images a bright surface while the leftmost red CCD, RED9, images a very dark surface. Clearly the two will receive very different electron signals, and thus RED0's data should not be used to represent RED9's histogram.

CCD Response Algorithm

The 14-bit DN value for a CCD is given by the following equation:

DN14 = (signal / inverse gain) + offset

The original signal in electron count is thus the following:

signal = (DN14 - offset) * inverse gain

Version:
2.8
Author:
Christian Schaller - UA/PIRL

Field Summary
static String CCD_DATA
          The name of the aggregate (group) Parameter under which all CCD data are stored.
static String CCD_DATA_FILENAME
          The name of the PVL file containing the CCD data.
static double DEFAULT_INVERSE_GAIN
          The default inverse gain for the histogram.
static double DEFAULT_OFFSET
          The default offset for the histogram.
static int DEFAULT_PIXELS
          The default pixel count for the CCD image this histogram represents.
static String ID
          Class identification name with source code version and date.
static String INVERSE_GAINS
          The name of the Parameter whose value is a set array of CCD inverse gains.
static int MAXIMUM_RANGE
          The maximum value of the histogram's range.
static int MINIMUM_RANGE
          The minimum value of the histogram's range.
static String OFFSET
          The name of the Parameter whose value is the CCD offset.
 
Constructor Summary
CCD_Histogram()
          Creates a new CCD histogram.
CCD_Histogram(int pixels)
          Creates a new CCD histogram given a number of pixels to represent.
CCD_Histogram(int mean, int std, double offset, double inverse_gain, int pixels)
          Creates a new CCD histogram with a Gaussian distribution in signal, a CCD offset, a CCD inverse gain, and the number of pixels to represent.
CCD_Histogram(Parameter hiphop_data)
          Creates a new CCD histogram given a HIPHOP CCD aggregate parameter.
CCD_Histogram(Parameter hiphop_data, double target_offset, double target_inverse_gain)
           
CCD_Histogram(Parameter hiphop_data, double target_offset, double target_inverse_gain, int pixels)
           
CCD_Histogram(Parameter hiphop_data, int pixels)
          Creates a new CCD histogram given a HIPHOP CCD aggregate parameter and number of pixels to represent.
CCD_Histogram(Parameter hiphop_data, String target_ccd_name)
           
CCD_Histogram(Parameter hiphop_data, String target_ccd_name, int pixels)
           
CCD_Histogram(short[] source_data)
          Creates a new CCD histogram given a set of source data.
CCD_Histogram(short[] source_data, int source_minimum)
          Creates a new CCD histogram given a set of source data and a source minimum value.
CCD_Histogram(short[] source_data, int source_minimum, double source_offset, double source_inverse_gain, double target_offset, double target_inverse_gain, int pixels)
          Creates a new CCD histogram given a set of source data, a source minimum value, source CCD properties, target CCD properties, and the number of pixels to represent.
CCD_Histogram(short[] source_data, int source_minimum, double source_offset, double source_inverse_gain, int pixels)
          Creates a new CCD histogram given a set of source data, a source minimum value, source CCD properties, and the number of pixels to represent.
 
Method Summary
static double ccd_inverse_gain(String ccd_name, int binning)
           
static double ccd_offset(String ccd_name)
           
 double getValue(double x)
          Returns the value of the function (y) for a given input (x).
 double mean()
          Gets the mean value of the target CCD histogram.
 int pixels()
          Gets the number of pixels represented by this histogram.
 void pixels(int pixels)
          Sets the number of pixels represented by this histogram.
 double source_frequency(double source_dn)
           
 double source_inverse_gain()
          Gets the CCD inverse gain for the source of this histogram data.
 int source_maximum()
          Gets the maximum DN14 value of this histogram.
 int source_minimum()
          Gets the minimum DN14 value of this histogram.
 double source_offset()
          Gets the CCD offset for the source of this histogram data.
 double source_to_target_dn(double source_dn)
           
 double standard_deviation()
          Gets the standard deviation of the target CCD histogram.
 double target_frequency(double target_dn)
           
 double target_inverse_gain()
          Gets the CCD inverse gain for the target detector represented by this histogram.
 void target_inverse_gain(double target_inverse_gain)
          Sets the CCD inverse gain for the target detector represented by this histogram.
 int target_maximum()
           
 int target_minimum()
           
 double target_offset()
          Gets the CCD offset for the target detector represented by this histogram.
 void target_offset(double target_offset)
          Sets the CCD offset for the target detector represented by this histogram.
 double target_to_source_dn(double target_dn)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

MINIMUM_RANGE

public static final int MINIMUM_RANGE
The minimum value of the histogram's range. For values smaller than this value, the histogram's count is 0.

See Also:
Constant Field Values

MAXIMUM_RANGE

public static final int MAXIMUM_RANGE
The maximum value of the histogram's range. For values larger than this value, the histogram's count is 0.

See Also:
Constant Field Values

DEFAULT_PIXELS

public static final int DEFAULT_PIXELS
The default pixel count for the CCD image this histogram represents. This value is a standard 2048-pixel wide HiRISE image with 10,000 lines. It is an arbitrary value, but it yields reasonable histograms.

See Also:
Constant Field Values

DEFAULT_INVERSE_GAIN

public static final double DEFAULT_INVERSE_GAIN
The default inverse gain for the histogram. It is the inverse gain for RED5, channel 0, at bin 1. This value comes from Alfred McEwen in a HIPHOP data file (hi_adc_1.txt) from September 14, 2006.

See Also:
Constant Field Values

DEFAULT_OFFSET

public static final double DEFAULT_OFFSET
The default offset for the histogram. It is the 20-degree Celsius offset for RED5, channel 0. This value comes from Alfred McEwen in a HIPHOP data file (hi_adc_1.txt) from September 14, 2006.

See Also:
Constant Field Values

CCD_DATA_FILENAME

public static final String CCD_DATA_FILENAME
The name of the PVL file containing the CCD data. The class loader expects to find this file in the directory named by Constants.RESOURCES_DIRECTORY.

See Also:
Constant Field Values

CCD_DATA

public static final String CCD_DATA
The name of the aggregate (group) Parameter under which all CCD data are stored.

See Also:
Constant Field Values

OFFSET

public static final String OFFSET
The name of the Parameter whose value is the CCD offset.

See Also:
Constant Field Values

INVERSE_GAINS

public static final String INVERSE_GAINS
The name of the Parameter whose value is a set array of CCD inverse gains.

See Also:
Constant Field Values
Constructor Detail

CCD_Histogram

public CCD_Histogram(short[] source_data,
                     int source_minimum,
                     double source_offset,
                     double source_inverse_gain,
                     double target_offset,
                     double target_inverse_gain,
                     int pixels)
Creates a new CCD histogram given a set of source data, a source minimum value, source CCD properties, target CCD properties, and the number of pixels to represent.

Parameters:
source_data - the source CCD histogram data.
source_minimum - the minimum 14-bit value in the histogram data; the integer value of source_offset is used if this value is less than 0.
source_offset - the CCD offset for the source of the histogram data; DEFAULT_OFFSET is used if this value is less than 0.
source_inverse_gain - the CCD inverse gain for the source of the histogram data; DEFAULT_INVERSE_GAIN is used if this value is less than 1.
target_offset - the CCD offset for the target to be represented by this CCD_Histogram; source_offset is used if this value is less than 0.
target_inverse_gain - the CCD inverse gain for the target to be represented by this CCD_Histogram; source_inverse_gain is used if this value is less than 1.
pixels - the total number of pixels in the histogram; DEFAULT_PIXELS is used if this value is less than 1.

CCD_Histogram

public CCD_Histogram(short[] source_data,
                     int source_minimum,
                     double source_offset,
                     double source_inverse_gain,
                     int pixels)
Creates a new CCD histogram given a set of source data, a source minimum value, source CCD properties, and the number of pixels to represent. The target CCD properties are set to those of the source CCD.

Parameters:
source_data - the source CCD histogram data.
source_minimum - the minimum 14-bit value in the histogram data; the integer value of source_offset is used if this value is less than 0.
source_offset - the CCD offset for the source of the histogram data; DEFAULT_OFFSET is used if this value is less than 0.
source_inverse_gain - the CCD inverse gain for the source of the histogram data; DEFAULT_INVERSE_GAIN is used if this value is less than 1.
pixels - the total number of pixels in the histogram; DEFAULT_PIXELS is used if this value is less than 1.

CCD_Histogram

public CCD_Histogram(short[] source_data,
                     int source_minimum)
Creates a new CCD histogram given a set of source data and a source minimum value. Defaults are used for the source CCD properties, the target CCD properties, and the number of pixels to represent.

Parameters:
source_data - the source CCD histogram data.
source_minimum - the minimum 14-bit value in the histogram data; the integer value of source_offset is used if this value is less than 0.

CCD_Histogram

public CCD_Histogram(short[] source_data)
Creates a new CCD histogram given a set of source data. Defaults are used for the source minimum, the source CCD properties, the target CCD properties, and the number of pixels to represent.

Parameters:
source_data - the source CCD histogram data.

CCD_Histogram

public CCD_Histogram(Parameter hiphop_data,
                     int pixels)
              throws PVL_Exception
Creates a new CCD histogram given a HIPHOP CCD aggregate parameter and number of pixels to represent. The CCD data parameter must be one of the aggregates described in Transfer_File_Parameters for the HiRISE CCDs. If it is not, a PVL_Exception will be thrown.

Parameters:
hiphop_data - the HIPHOP histogram data.
pixels - the total number of pixels in the histogram; DEFAULT_PIXELS is used if this value is less than 1.
Throws:
PVL_Exception - if the HIPHOP data parameter is not the right format.

CCD_Histogram

public CCD_Histogram(Parameter hiphop_data)
              throws PVL_Exception
Creates a new CCD histogram given a HIPHOP CCD aggregate parameter. A default value is used for the number of pixels to represent. The CCD data parameter must be one of the aggregates described in Transfer_File_Parameters for the HiRISE CCDs. If it is not, a PVL_Exception will be thrown.

Parameters:
hiphop_data - the HIPHOP histogram data.
Throws:
PVL_Exception - if the HIPHOP data parameter is not the right format.

CCD_Histogram

public CCD_Histogram(Parameter hiphop_data,
                     String target_ccd_name,
                     int pixels)
              throws PVL_Exception,
                     FileNotFoundException,
                     Invalid_Argument_Exception
Throws:
PVL_Exception
FileNotFoundException
Invalid_Argument_Exception

CCD_Histogram

public CCD_Histogram(Parameter hiphop_data,
                     String target_ccd_name)
              throws PVL_Exception,
                     FileNotFoundException,
                     Invalid_Argument_Exception
Throws:
PVL_Exception
FileNotFoundException
Invalid_Argument_Exception

CCD_Histogram

public CCD_Histogram(Parameter hiphop_data,
                     double target_offset,
                     double target_inverse_gain,
                     int pixels)
              throws PVL_Exception
Throws:
PVL_Exception

CCD_Histogram

public CCD_Histogram(Parameter hiphop_data,
                     double target_offset,
                     double target_inverse_gain)
              throws PVL_Exception
Throws:
PVL_Exception

CCD_Histogram

public CCD_Histogram(int mean,
                     int std,
                     double offset,
                     double inverse_gain,
                     int pixels)
Creates a new CCD histogram with a Gaussian distribution in signal, a CCD offset, a CCD inverse gain, and the number of pixels to represent. The distribution is defined by a mean value and a standard deviation.

Parameters:
mean - the mean value of the Gaussian distribution; a random value is used if this value is less than 1.
std - the standard deviation of the Gaussian distribution; a random value is used if this value is less than 1.
offset - the offset for the histogram data, for both the source CCD and the target CCD; DEFAULT_OFFSET is used if this value is less than 0.
inverse_gain - the inverse gain for the histogram data, for both the source CCD and the target CCD; DEFAULT_INVERSE_GAIN is used if this value is less than 1.
pixels - the total number of pixels in the histogram; DEFAULT_PIXELS is used if this value is less than 1.

CCD_Histogram

public CCD_Histogram(int pixels)
Creates a new CCD histogram given a number of pixels to represent. A random Gaussian distribution is used for the histogram data, and default values are used for the CCD offset and CCD inverse gain.

Parameters:
pixels - the total number of pixels in the histogram; DEFAULT_PIXELS is used if this value is less than 1.

CCD_Histogram

public CCD_Histogram()
Creates a new CCD histogram. A random Gaussian distribution is used for the histogram data, and default values are used for the CCD offset, CCD inverse gain, and number of pixels to represent.

Method Detail

source_offset

public double source_offset()
Gets the CCD offset for the source of this histogram data. Note that there is no corresponding setter for this parameter.

Returns:
the source CCD offset.

source_inverse_gain

public double source_inverse_gain()
Gets the CCD inverse gain for the source of this histogram data. Note that there is no corresponding setter for this parameter.

Returns:
the source CCD inverse gain.

source_minimum

public int source_minimum()
Gets the minimum DN14 value of this histogram. The minimum should at least be the same as the offset in general; occasionally, however, it is smaller when the histogram is constructed from a HIPHOP output Parameter.

All DN14 values less than the minimum have a count of zero.

Returns:
the histogram's minimum DN14 value.

source_maximum

public int source_maximum()
Gets the maximum DN14 value of this histogram. It is the minimum value plus the number of points in the histogram data.

All DN14 values greater than the maximum have a count of zero.

Returns:
the histogram's maximum value.

target_offset

public double target_offset()
Gets the CCD offset for the target detector represented by this histogram.

Returns:
the target CCD offset.

target_offset

public void target_offset(double target_offset)
Sets the CCD offset for the target detector represented by this histogram.

Parameters:
target_offset - the new target CCD offset.

target_inverse_gain

public double target_inverse_gain()
Gets the CCD inverse gain for the target detector represented by this histogram.

Returns:
the target CCD inverse gain.

target_inverse_gain

public void target_inverse_gain(double target_inverse_gain)
Sets the CCD inverse gain for the target detector represented by this histogram.

Parameters:
target_inverse_gain - the new target CCD inverse gain.

target_minimum

public int target_minimum()

target_maximum

public int target_maximum()

pixels

public int pixels()
Gets the number of pixels represented by this histogram.

Returns:
the total number of pixels in the histogram.

pixels

public void pixels(int pixels)
Sets the number of pixels represented by this histogram.

Parameters:
pixels - the new total number of pixels in the histogram.

mean

public double mean()
Gets the mean value of the target CCD histogram.

Returns:
the mean.

standard_deviation

public double standard_deviation()
Gets the standard deviation of the target CCD histogram.

Returns:
the standard deviation.

getValue

public double getValue(double x)
Returns the value of the function (y) for a given input (x). In the case of a CCD_Histogram, the value of the function is the pixel count for the input 14-bit DN value x. x is a 14-bit DN value for the target CCD, as defined by the target_offset and target_inverse_gain; the pixel count is thus that for the target CCD.

The function value is scaled such that the total area under the histogram from target_minimum() to target_maximum() 14-bit DN value, equals the number of pixels represented.

Specified by:
getValue in interface Function2D
Parameters:
x - the input x-value, a 14-bit pixel brightness for the target CCD.
Returns:
the function value, the histogram count for the input DN14.

source_frequency

public double source_frequency(double source_dn)

target_frequency

public double target_frequency(double target_dn)

source_to_target_dn

public double source_to_target_dn(double source_dn)

target_to_source_dn

public double target_to_source_dn(double target_dn)

ccd_offset

public static double ccd_offset(String ccd_name)
                         throws PVL_Exception,
                                FileNotFoundException,
                                Invalid_Argument_Exception
Throws:
PVL_Exception
FileNotFoundException
Invalid_Argument_Exception

ccd_inverse_gain

public static double ccd_inverse_gain(String ccd_name,
                                      int binning)
                               throws PVL_Exception,
                                      FileNotFoundException,
                                      Invalid_Argument_Exception
Throws:
PVL_Exception
FileNotFoundException
Invalid_Argument_Exception

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona