			caminfo Modifications
			  September 18, 2008


The caminfo application used by the UPC has had some extensive changes made to 
support cubes where the bands have dependent geometry.  This means each band in 
the cube has a different geometric footprint.  THEMIS IR and VIS are but one 
example where bands have different geometric characteristics.

caminfo is perhaps the most critical application in the processing of UPC data.  
It computes and/or stores of all data that eventually is populated in the UPC 
database.  This document describes the changes and alludes to the impact it may 
have on others who have come to rely on caminfo for their processing needs.

Structural Changes
The change with the most impact is a restructuring of the PVL Object and Group 
structure of the resulting PVL output file.  No longer is each band's 
individual geometry included in the PVL.  The "BandSet" object has been removed 
from the PVL.  All "Band" groups that report individual geometry 
characteristics have been removed.  In general, All Groups have been replaced 
with objects that are named the same as the parameters in the user interface.

The top level object was renamed from "Parameters" to "Caminfo", the name of 
the application.  The "Common" object has been renamed to "Parameters" and only 
IsisId, From, Lines, Samples and Bands are contained therein.  This is a big 
change from the old structure as the top level Object was named "Parameters" 
and the "Common" Object contained all other Pvl structures.  This essentially 
eliminates an entire level of object nesting.

The "CubeCamStats" Group has been renamed to the "Camstats" Object and is 
contained in the "Caminfo" top level object.

The statistics keywords in each old "Band" Group have been consolidated into 
the "Statistics" Object.  This object is new and now includes all data in all 
bands of the input cube.  This differs from the old version in that it only was 
generated for each band an no data was available for the whole file.  One 
casualty occured in that the "MedianValue" keyword is no longer calculated.  
This required two passes and was not the true median of the cube when they are 
in floating point format.  Note that in order to get the true median of a 
dataset, the entire dataset must stored and sorted in order and the exact 
middle value will be the median.  This is impractical for large files.

The Group "Band" in the "BandSet" Object has been replaced with the "Geometry" 
Object in the "Caminfo" top level object.  The "BandSet" Object has been 
removed entirely.  Note that a "Band" Group was generated for each band in a 
mult-band cube.  Bands are no longer being treated this way.  They are 
consolidated as	a union of all band dependent bands. This is discussed in 
detail below.

The geometry characteristics contained in each "Band" Group are now 
consolidated for all bands and contained in the "Geometry" Object.  The 
Geometry Object is contained in the "Caminfo" top level object.  This new 
object is a union of the geometric characteristics for all band dependent data 
or simply the first band for data that is band independent.  

Some additional keywords have been added to the new "Geometry" Object.  Many
of the keywords that were in the "Band" Group are retained, however, they
should be deemed representative of the complete image cube geometry and not 
just one band. They are:

BandsUsed         - reports the number of bands used to generate the data
ReferenceBand     - This reports the logical band used to describe the geometry 
                    excluding the corners latitude/longitude keywords.  This 
                    reference band is selected as the band whose center 
                    latitude is closest to the Centroid latitude/longitude of 
                    the combined polygon of all bands.
OriginalBand      - The physical band of ReferenceBand.  Many times they will 
                    be one in the same.
Target            - Name of the target observed.  This may be necessary if no
                    label output option is selected.
CenterRadius      - The "local" radius at the CenterLatitude/CenterLongitude 
                    coordinate.  This may be the radius of the spheroid or the 
		    DEM if one is available.
CentroidLatitude  - Latitude coordinate of the centroid of the polygon.  This 
                    is computed using the union polygon of all bands.
CentroidLongitude - Longitude coordinate of the centroid of the polygon.  This 
                    is computed using the union polygon of all bands.
CentroidLine      - Reports the line coordinate in the image where the polygon 
                    centroid point is located.
CentroidSample    - Reports the sample coordinate in the image where the 
                    polygon centroid point is located.
CentroidRadius    - "Local" radius at the polygon centroid.  This may differ 
                    from the CenterRadius.
MeanGroundResolution - Average of the lowest and highest occuring image 
                       resolution.


Band-by-Band Processing
The biggest change in caminfo is perhaps how each band is considered in the 
gathering of cube and geometry statistics and the characterization of the cube 
geometry and polygon footprint for the product.  Note that as far as I am 
concerned, a UPC product or database entry refers uniquely to a single file.  
It is with this in mind	that motivated the choices made in implementing the 
current version of caminfo.

For band independant image cubes, only the first band is used to generate the 
"Geometry" object.  For band dependent data, the following processes are 
employed:

1)  Polygons for all data are generated regardless as to if the user requested 
polygon information.  Polygons are used to assist in the full Geometry 
characterization.

2)  The polygons for each band are unioned into one final multipolygon that 
characterizes the full geometric footprint for all bands in the cube.

3)  The centroid latitude and longitude point is calculated for each band
polygon.  This point is converted to line and sample and the local radius at 
that position is recorded.

4)  The centroid point for the combined union polygon of all bands is computed.

5)  The union centroid point is used to determine the four corner 
latitude/longitude points in the following fashion:
	a) Each bands geometry is saved storing information that is reported
	   in the Geometry object.
	b) At each corner the distance from the polygon centroid point to the 
           corner latitude/longitude point is computed.
	c) The point that is furthest from the centroid point is saved as the
	   corner point.
	d) All four corners are computed this way.

The "Polygon" Object contains the GisFootprint along wth some new information.  
In additon to the Well Known Text (WKT) format of the GIS footprint, the 
centroid latitude/longitude point of the union polygon is recorded.  

Also reported is the Radius computed according to the following procedure:
	a)  The average radius of the image center and polygon center are 
            computed independantly.
        b)  If the polygon radius is valid, it is the reported Radius.
	c)  Otherwise the center image point radius is returned if it is valid.
	d)  And finally, if neither of the above two radii are valid, the
	    radius from the average of the three radii reported in the SPICE 
            kernels is reported.

New to the "Polygon" Object is the surface area of the full polygon in units of 
square kilometers.  The surface area of the polygon is computed by projecting 
the full footprint polygon into a sinusoidal projection in global map X/Y 
coordinates.  These coordinates are in meters.  Then I use the GEOS getArea()
function of the polygon to compute the area of the polygon.

Once this is computed, the global surface area in square kilometers is computed 
as: 
	4.0 * PI * radius^2 / (1000.0*1000.0)

Then the ratio of polygon area to global area is calculated and converted to a 
percentage of global coverage.  This may be very helpful in the query process 
to eliminate wide angle images or select a range of images within a certain 
area resolution.

Note that it is simple to compute individual band Geometry to emulate much of 
how the old version computed band dependent geometry individually.  Simply use 
the band selection command line option to select the desired band to compute.  
In my opinion, this approach is easier to manage as the PVL format remains 
identical and is easier to manipulate with other tools outside the ISIS 
programming environment (such as getkey, etc...).

Here is a small diagram comparing the structural differences of the old version 
and new version of the PVL output file format:

----  OLD FORMAT ----                 ----  NEW FORMAT ----              
Object = Parameters                   Object = Caminfo                   
  Object = Common                       Object = Parameters              
    Group = CubeCamStats                EndObject                        
    EndGroup                            Object = Camstats                
  EndObject                             EndObject                        
  Object = IsisLabel                    Object = IsisLabel               
  EndObject                             EndObject                        
  Object = OriginalLabel                Object = OriginalLabel           
  EndObject                             EndObject                        
  Object = BandSet                      Object = Statistics              
    Group = Band                        EndObject                        
      Band =1                           Object = Geometry                
    EndGroup                            EndObject                        
    Group = Band                        Object = Polygon                 
      Band = 2                          EndObject                        
    EndGroup                          EndObject                          
  EndObject                           End                                
EndObject                             
End


Attached are some examples of old and new output.  If you would like to see the 
images used to calculate these examples, please come see me.

If you have strong objections to these modifications, you should bring them to 
my attention ASAP as I need to commit these changes to CVS and use it to 
restart pipeline processing.

Thanks...
				    



















			      
