diff --git a/isis/src/base/objs/CameraStatistics/CameraStatistics.cpp b/isis/src/base/objs/CameraStatistics/CameraStatistics.cpp index 8d9252ed3f80d059bc37486734c186aa3db90b3f..db76ea23f1b5c78d71acdcdbc33d7b5175e12372 100644 --- a/isis/src/base/objs/CameraStatistics/CameraStatistics.cpp +++ b/isis/src/base/objs/CameraStatistics/CameraStatistics.cpp @@ -8,6 +8,22 @@ #include "Statistics.h" namespace Isis { + + + /** + * Constructs the Camera Statistics object from a Cube filename. This + * constructor will first open the cube corresponding to the "filename" + * parameter, then gather statistics with the Cube's Camera. Neither the + * Cube nor its Camera is retained after statistics gathering has completed, + * but the filename used to open the Cube will be output in the "User + * Parameters" group of the "toPvl" method. The invoker of this constructor + * must also specify the sample and line increments to be used during + * statistics gathering. + * + * @param filename String filename of the Cube whose Camera will be used + * @param sinc Sample increment for gathering statistics + * @param linc Line increment for gathering statistics + */ CameraStatistics::CameraStatistics(std::string filename, int sinc, int linc) { Cube cube; cube.Open(filename); @@ -16,17 +32,57 @@ namespace Isis { } + /** + * Constructs the Camera Statistics object from an already-existent Camera + * pointer. Specifying sample and line increments of 1 will gather + * statistics on the entire area encompassed by the Camera, but higher + * numbers can be used to improve performance. Using this + * constructor--lacking a Cube filename--the "toPvl" method will not output + * the Cube filename associated with the Camera. If the user desires this + * information, there is a constructor that will take the filename purely for + * this purpose. + * + * @param cam Camera pointer upon which statistics will be gathered + * @param sinc Sample increment for gathering statistics + * @param linc Line increment for gathering statistics + */ CameraStatistics::CameraStatistics(Camera *cam, int sinc, int linc) { init(cam, sinc, linc, ""); } + /** + * Constructs the Camera Statistics object from an already-existent Camera + * pointer. Specifying sample and line increments of 1 will gather + * statistics on the entire area encompassed by the Camera, but higher + * numbers can be used to improve performance. The filename provided does + * not serve a functional purpose during the statistics gathering process, + * but will report the filename used to create the Camera instance in the + * "User Parameters" section of the PVL output from the "toPvl" method. + * + * @param cam Camera pointer upon which statistics will be gathered + * @param sinc Sample increment for gathering statistics + * @param linc Line increment for gathering statistics + * @param filename String filename of the Cube whose Camera is being used + */ CameraStatistics::CameraStatistics(Camera *cam, int sinc, int linc, std::string filename) { init(cam, sinc, linc, filename); } + /** + * Initializes this collection of statistics by incrementing over sample/line + * positions in the Camera and compiling various Camera values at those + * locations into all the Statistics objects maintained as the persistent + * state of the object. Statistics can be added to these objects later using + * the "addStats" method. + * + * @param cam Camera pointer upon which statistics will be gathered + * @param sinc Sample increment for gathering statistics + * @param linc Line increment for gathering statistics + * @param filename String filename of the Cube whose Camera is being used + */ void CameraStatistics::init(Camera *cam, int sinc, int linc, std::string filename) { @@ -50,30 +106,34 @@ namespace Isis { int eband = cam->Bands(); // If the camera is band independent then only run one band - if(cam->IsBandIndependent()) eband = 1; + if (cam->IsBandIndependent()) eband = 1; int pTotal = eband * ((cam->Lines() - 2) / linc + 2); Progress progress; progress.SetMaximumSteps(pTotal); progress.CheckStatus(); - for(int band = 1; band <= eband; band++) { + for (int band = 1; band <= eband; band++) { cam->SetBand(band); - for(int line = 1; line < (int)cam->Lines(); line = line + linc) { - for(int sample = 1; sample < cam->Samples(); sample = sample + sinc) { + for (int line = 1; line < (int)cam->Lines(); line = line + linc) { + for (int sample = 1; sample < cam->Samples(); sample = sample + sinc) { addStats(cam, sample, line); } - //set the sample value to the last sample and run buildstats + + // Set the sample value to the last sample and run buildstats int sample = cam->Samples(); addStats(cam, sample, line); progress.CheckStatus(); } - //set the line value to the last line and run on all samples(sample + sinc) + + // Set the line value to the last line and run on all samples (sample + + // sinc) int line = cam->Lines(); - for(int sample = 1; sample < cam->Samples(); sample = sample + sinc) { + for (int sample = 1; sample < cam->Samples(); sample = sample + sinc) { addStats(cam, sample, line); } - //set last sample and run with last line + + // Set last sample and run with last line int sample = cam->Samples(); addStats(cam, sample, line); progress.CheckStatus(); @@ -81,6 +141,9 @@ namespace Isis { } + /** + * Destroy this instance, deletes all the Statistics objects. + */ CameraStatistics::~CameraStatistics() { if (m_latStat != NULL) { delete m_latStat; @@ -133,8 +196,14 @@ namespace Isis { } - //function to add stats data to the stats object. - //also tests if the line and samp are valid + /** + * Add statistics data to Statistics objects if the Camera position given by + * the provided line and sample is looking at the surface of the target. + * + * @param cam Camera pointer upon which statistics are being gathered + * @param sample Sample of the image to gather Camera information on + * @param line Line of the image to gather Camera information on + */ void CameraStatistics::addStats(Camera *cam, int &sample, int &line) { cam->SetImage(sample, line); if(cam->HasSurfaceIntersection()) { @@ -156,13 +225,16 @@ namespace Isis { } - /** Produces NULL values for special pixels + /** + * Takes a name, value, and optionally units and constructs a PVL Keyword. + * If the value is determined to be a "special pixel", then the string NULL + * will be used for the value. * - * @param keyname Name of keyword to generate - * @param value Value to write to keyword - * @param unit Optional units for keywords + * @param keyname Name of keyword to generate + * @param value Value to write to keyword + * @param unit Optional units for keywords * - * @return PvlKeyword Newly created keyword + * @return PvlKeyword Keyword constructed from input parameters */ PvlKeyword CameraStatistics::constructKeyword(std::string keyname, double value, std::string unit="") const { @@ -176,6 +248,80 @@ namespace Isis { } + /** + * Constructs a Pvl object from the values in the various statistics objects. + * The general format will look as follows: + * + * @code + * Group = User Parameters + * Filename (not provided for constructor w/ Camera but not filename) + * Linc + * Sinc + * End_Group + * Group = Latitude + * LatitudeMinimum + * LatitudeMaximum + * LatitudeStandardDeviation + * End_Group + * Group = Longitude + * LongitudeMinimum + * LongitudeMaximum + * LongitudeStandardDeviation + * End_Group + * Group = SampleResolution + * SampleResolutionMinimum + * SampleResolutionMaximum + * SampleResolutionStandardDeviation + * End_Group + * Group = LineResolution + * LineResolutionMinimum + * LineResolutionMaximum + * LineResolutionStandardDeviation + * End_Group + * Group = Resolution + * ResolutionMinimum + * ResolutionMaximum + * ResolutionStandardDeviation + * End_Group + * Group = AspectRatio + * AspectRatioMinimum + * AspectRatioMaximum + * AspectRatioStandardDeviation + * End_Group + * Group = PhaseAngle + * PhaseMinimum + * PhaseMaximum + * PhaseStandardDeviation + * End_Group + * Group = EmissionAngle + * EmissionMinimum + * EmissionMaximum + * EmissionStandardDeviation + * End_Group + * Group = IncidenceAngle + * IncidenceMinimum + * IncidenceMaximum + * IncidenceStandardDeviation + * End_Group + * Group = LocalSolarTime + * LocalSolarTimeMinimum + * LocalSolarTimeMaximum + * LocalSolarTimeStandardDeviation + * End_Group + * Group = LocalRadius + * LocalRadiusMinimum + * LocalRadiusMaximum + * LocalRadiusStandardDeviation + * End_Group + * Group = NorthAzimuth + * NorthAzimuthMinimum + * NorthAzimuthMaximum + * NorthAzimuthStandardDeviation + * End_Group + * @endcode + * + * @return Pvl PVL collection of all values for all statistics gathered + */ Pvl CameraStatistics::toPvl() const { // Set up the Pvl groups and get min, max, avg, and sd for each statstics // object @@ -294,7 +440,5 @@ namespace Isis { returnPvl.AddGroup(pNorthAzimuth); return returnPvl; } - - -} // End namespace Isis +} diff --git a/isis/src/base/objs/CameraStatistics/CameraStatistics.h b/isis/src/base/objs/CameraStatistics/CameraStatistics.h index 04776b0e79a01de24f4cb5fe8ebaeada8730570d..02d680b5231cb47135f16692370ccbadaf16c7ca 100644 --- a/isis/src/base/objs/CameraStatistics/CameraStatistics.h +++ b/isis/src/base/objs/CameraStatistics/CameraStatistics.h @@ -1,3 +1,6 @@ +#ifndef CameraStatistics_h +#define CameraStatistics_h + /** * @file * $Revision: 1.16 $ @@ -21,9 +24,6 @@ * http://www.usgs.gov/privacy.html. */ -#ifndef CameraStatistics_h -#define CameraStatistics_h - #include namespace Isis { @@ -32,6 +32,26 @@ namespace Isis { class PvlKeyword; class Statistics; + /** + * @brief Calculates a series of statistics pertaining to a Camera. + * + * Given a Camera pointer--or the filename of a Cube whose Camera is to be + * used--this class will calculate a series of statistics at initialization + * on the Camera. After construction, the user can retrieve statistics, + * compiled for every line/sample of the Camera, for the Camera's latitude, + * longitude, pixel resolution, sample resolution, line resolution, phase + * angle, emission angle, incidence angle, local solar time, meters, north + * azimuth, and aspect ratio. + * + * @ingroup SpiceInstrumentsAndCameras + * + * @author 2011-06-14 Travis Addair + * + * @internal + * @history 2011-06-14 Travis Addair - Extracted logic from "camstats" + * application to create this class. + */ + class CameraStatistics { public: CameraStatistics(std::string filename, int sinc, int linc); @@ -44,50 +64,134 @@ namespace Isis { std::string unit) const; Pvl toPvl() const; + + /** + * Accessor method for inspecting the statistics gathered on the + * Universal Latitudes of the input Camera. + * + * @return Statistics * Constant pointer to Latitude Statistics + */ const Statistics * getLatStat() const { return m_latStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Universal Longitudes of the input Camera. + * + * @return Statistics * Constant pointer to Longitude Statistics + */ const Statistics * getLonStat() const { return m_lonStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Pixel Resolutions of the input Camera. + * + * @return Statistics * Constant pointer to Pixel Resolution Statistics + */ const Statistics * getResStat() const { return m_resStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Sample Resolutions of the input Camera. + * + * @return Statistics * Constant pointer to Sample Resolution Statistics + */ const Statistics * getSampleResStat() const { return m_sampleResStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Line Resolution of the input Camera. + * + * @return Statistics * Constant pointer to Line Resolution Statistics + */ const Statistics * getLineResStat() const { return m_lineResStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Aspect Ratios of the input Camera. + * + * @return Statistics * Constant pointer to Aspect Ratio Statistics + */ const Statistics * getAspectRatioStat() const { return m_aspectRatioStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Phase Angles of the input Camera. + * + * @return Statistics * Constant pointer to Phase Angle Statistics + */ const Statistics * getPhaseStat() const { return m_phaseStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Emission Angles of the input Camera. + * + * @return Statistics * Constant pointer to Emission Angle Statistics + */ const Statistics * getEmissionStat() const { return m_emissionStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Incidence Angles of the input Camera. + * + * @return Statistics * Constant pointer to Incidence Angle Statistics + */ const Statistics * getIncidenceStat() const { return m_incidenceStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Local Solar Times of the input Camera. + * + * @return Statistics * Constant pointer to Local Solar Time Statistics + */ const Statistics * getLocalSolarTimeStat() const { return m_localSolarTimeStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * Local Radii (in meters) of the input Camera. + * + * @return Statistics * Constant pointer to Local Radius Statistics + */ const Statistics * getLocalRaduisStat() const { return m_localRaduisStat; }; + + /** + * Accessor method for inspecting the statistics gathered on the + * North Azimuths of the input Camera. + * + * @return Statistics * Constant pointer to North Azimuth Statistics + */ const Statistics * getNorthAzimuthStat() const { return m_northAzimuthStat; }; @@ -95,22 +199,23 @@ namespace Isis { private: void init(Camera *cam, int sinc, int linc, std::string filename); + //!< Filename of the Cube the Camera was derived from. std::string m_filename; - int m_sinc; - int m_linc; - - Statistics *m_latStat; - Statistics *m_lonStat; - Statistics *m_resStat; - Statistics *m_sampleResStat; - Statistics *m_lineResStat; - Statistics *m_aspectRatioStat; - Statistics *m_phaseStat; - Statistics *m_emissionStat; - Statistics *m_incidenceStat; - Statistics *m_localSolarTimeStat; - Statistics *m_localRaduisStat; - Statistics *m_northAzimuthStat; + int m_sinc; //!< Sample increment for composing statistics. + int m_linc; //!< Line increment for composing statistics. + + Statistics *m_latStat; //!< Universal latitude statistics. + Statistics *m_lonStat; //!< Universal longitude statistics. + Statistics *m_resStat; //!< Pixel resolution statistics. + Statistics *m_sampleResStat; //!< Sample resolution statistics. + Statistics *m_lineResStat; //!< Line resolution statistics. + Statistics *m_aspectRatioStat; //!< Aspect ratio statistics. + Statistics *m_phaseStat; //!< Phase angle statistics. + Statistics *m_emissionStat; //!< Emission angle statistics. + Statistics *m_incidenceStat; //!< Incidence angle statistics. + Statistics *m_localSolarTimeStat; //!< Local solar time statistics. + Statistics *m_localRaduisStat; //!< Local radius statistics (in meters). + Statistics *m_northAzimuthStat; //!< North azimuth statistics. }; };