Home
About ISIS
Support
Download

ISIS 3

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents

Search
USGS

ISIS 3 Application Documentation

caminfo

Standard View | TOC | Home

Outputs a PVL file that contains camera information.

Description
Categories
Groups
History

Description

This program compiles and outputs various spacecraft and instrument-related information such as geometric, polygon, and mapping information.

The user must supply a Level1 cube. If the supplied cube does not have SPICE information associated with it, then caminfo can be used to generate the SPICE information by running the spiceinit program on the cube. Caminfo will not run spiceinit by default. If the input cube already has SPICE information associated with it, then any user updates to the SPICE information will be lost when the option to run spiceinit is chosen. This results from using system defaults when running the spiceinit program from within caminfo.

Some information in the output PVL file will consist of a compilation of information for all the bands in the cube and will be listed in the "Common" object of the PVL. Other information for a given band will be placed in the "BandSet" object of the PVL. The user can select the check boxes to control the information that will be output to the PVL file. If the POLYGON or USELABEL option is chosen, the image polygon is output in Well-Known Text format (WKT).

The output file can be in PVL or CSV (Comma Separated Value) format. The "APPEND" option allows the new generated information to be appended to the output file. This is especially useful for CSV file format. If the CSV format is chosen, only Camstats, Statistics and Geometry options are allowed. Isis Label, Original Label and Polygon options are disabled for CSV format.

The following is an example of caminfo output generated when in PVL format: 

 
Object = Caminfo
  Object = Parameters
    Program     = caminfo
    IsisVersion = "3.4.2.0 alpha | 2012-08-28"
    RunDate     = 2012-11-23T18:21:42
    IsisId      = MeSSEnGeR/MDIS-WAC/1/0250507146:955000
    From        = EW0250507146G.lev1.cub
    Lines       = 512
    Samples     = 512
    Bands       = 1
  End_Object

  Object = Camstats
    MinimumLatitude   = 57.872627357566
    MaximumLatitude   = 61.299709008025
    MinimumLongitude  = 18.065988732773
    MaximumLongitude  = 24.841561067248
    MinimumResolution = 229.97591146546
    MaximumResolution = 232.50589076348
    MinimumPhase      = 75.229196963297
    MaximumPhase      = 85.75524278645
    MinimumEmission   = 0.010416983765103
    MaximumEmission   = 9.5170724264221
    MinimumIncidence  = 78.991903468001
    MaximumIncidence  = 81.783782038128
    LocalTimeMinimum  = 7.0686934940095
    LocalTimeMaximum  = 7.5203983163079
  End_Object

  Object = Geometry
    BandsUsed                  = 1
    ReferenceBand              = 1
    OriginalBand               = 1
    Target                     = Mercury
    StartTime                  = 2012-07-11T15:14:40.902702
    EndTime                    = 2012-07-11T15:14:40.902702
    CenterLine                 = 256.0
    CenterSample               = 256.0
    CenterLatitude             = 59.604440922996
    CenterLongitude            = 21.354478199267
    CenterRadius               = 2440000.0
    RightAscension             = 149.14971069552
    Declination                = -47.692390719996
    UpperLeftLongitude         = 19.403075966477
    UpperLeftLatitude          = 61.299709008025
    LowerLeftLongitude         = 18.065988732773
    LowerLeftLatitude          = 58.619183968695
    LowerRightLongitude        = 23.126850062052
    LowerRightLatitude         = 57.872627357566
    UpperRightLongitude        = 24.841561067248
    UpperRightLatitude         = 60.495929386174
    PhaseAngle                 = 80.450057821076
    EmissionAngle              = 0.19786246622852
    IncidenceAngle             = 80.389167381747
    NorthAzimuth               = 253.73558748868
    OffNadir                   = 0.15660719057979
    SolarLongitude             = 228.88911417663
    LocalTime                  = 7.2879261251091
    TargetCenterDistance       = 3082.770704015
    SlantDistance              = 642.77373761039
    SampleResolution           = 229.97699384231
    LineResolution             = 229.97699384231
    PixelResolution            = 229.97699384231
    MeanGroundResolution       = 231.24575069814
    SubSolarAzimuth            = 0.57284290603718
    SubSolarGroundAzimuth      = 106.83729602467
    SubSolarLatitude           = -0.026413277465333
    SubSolarLongitude          = 92.035586322631
    SubSpacecraftAzimuth       = 252.66562276234
    SubSpacecraftGroundAzimuth = 358.93004128485
    SubSpacecraftLatitude      = 59.645688996553
    SubSpacecraftLongitude     = 21.352953761563
    ParallaxX                  = -0.0034527631018843
    ParallaxY                  = -6.44854385850795e-05
    ShadowX                    = 1.7105756767263
    ShadowY                    = 5.6523998602669
    HasLongitudeBoundary       = FALSE
    HasNorthPole               = FALSE
    HasSouthPole               = FALSE
  End_Object

  Object = Polygon
    CentroidLine      = 258.34023273956
    CentroidSample    = 257.21847692747
    CentroidLatitude  = 59.590465340438
    CentroidLongitude = 21.359965088916
    CentroidRadius    = 2440000.0 <meters>
    SurfaceArea       = 13898.794042461 <km^2>
    GlobalCoverage    = 0.018578 <percent>
    SampleIncrement   = 51
    LineIncrement     = 51
    GisFootprint      = "MULTIPOLYGON (((19.4043245299965577
                         61.3023495859178169, 19.9591033663380273
                         61.2315368240940714, 20.5109136331950097
                         61.1586516900412036, 21.0599888059494056
                         61.0836769590772022, 21.6064014066990424
                         61.0066139869781026, 22.1502234714845763
                         60.9274625969637071, 22.6915266780484934
                         60.8462210727062072, 23.2303824713721276
                         60.7628861464013283, 23.7668621875485293
                         60.6774529818562556, 24.3010371765409943
                         60.5899151525158430, 24.8329789243747072
                         60.5002646143153129, 24.8468003809156031
                         60.4950897448882969, 24.6621540377068555
                         60.2342816512584278, 24.4808344234486128
                         59.9734256463113198, 24.3026802658222785
                         59.7124215421160969, 24.1275717810041321
                         59.4512190020262992, 23.9553945002749487
                         59.1897673396973545, 23.7860389348923675
                         58.9280154365526201, 23.6194002639650478
                         58.6659116571399295, 23.4553780433470500
                         58.4034037620610960, 23.2938759337506376
                         58.1404388181350171, 23.1348014464353007
                         57.8769631054306473, 23.1253981883423947
                         57.8700250132380773, 22.6291388167111727
                         57.9542062153035644, 22.1311712748992804
                         58.0362115673268590, 21.6313369328161791
                         58.1160668824232829, 21.1295724335347970
                         58.1937799049820939, 20.6258143687462976
                         58.2693567261389802, 20.1199991639326754
                         58.3428018062430951, 19.6120629625565215
                         58.4141179920416960, 19.1019415087693858
                         58.4833065286652030, 18.5895700281331031
                         58.5503670664614404, 18.0748831058364949
                         58.6152976626940756, 18.0609063686927200
                         58.6197579732196061, 18.1862320670262285
                         58.8883242752207750, 18.3131290280031429
                         59.1564691086538232, 18.4416916210760888
                         59.4243018649568882, 18.5719929967238073
                         59.6918797207437137, 18.7041092262310542
                         59.9592593996394498, 18.8381195168780309
                         60.2264972751596446, 18.9741064422031833
                         60.4936494719392712, 19.1121561888774671
                         60.7607719657418741, 19.2523588218842434
                         61.0279206826665117, 19.3948085698758135
                         61.2951515979628851, 19.4043245299965577
                         61.3023495859178169)))"

    Group = Mapping
      TargetName         = Mercury
      EquatorialRadius   = 2440000.0 <meters>
      PolarRadius        = 2440000.0 <meters>
      LatitudeType       = Planetocentric
      LongitudeDirection = PositiveEast
      LongitudeDomain    = 360
      MinimumLatitude    = 57.869205530706
      MaximumLatitude    = 61.303013149342
      MinimumLongitude   = 18.059709527443
      MaximumLongitude   = 24.848591196067
      PixelResolution    = 229.97590845703
      ProjectionName     = Sinusoidal
      CenterLongitude    = 21.354478199267
    End_Group
  End_Object
End_Object
End

Output values that do not have a minimum/maximum range associated with them are calculated at the center of the image.

Definitions for most of the values output in the PVL file can be found in the ISIS 3 documentation glossary including: SubSpacecraftLatitude, SubSpacecraftLongitude, SubSolarLatitude, SubSolarLongitude, NorthAzimuth, SpacecraftAzimuth, and SubSolarAzimuth,

Categories

Parameter Groups

Files

Name Description
FROM Filename of a cube
TO Output PVL filename

General Output Options

Name Description
FORMATFormat type of Output file (FLAT or PVL)
APPENDAppend caminfo information to existing data file
GEOMETRY Include geometry information
ISISLABEL Include ISIS label
ORIGINALLABEL Include the original label
STATISTICS Include DN statistics
CAMSTATS Get camera statistics information
LINC LINC line increments for camstats
SINC SINC sample increments for camstats

Polygon Output Options

Name Description
USELABEL Get footprint blob from label
POLYGON Create polygon information
INCTYPE Polygon quality
INCREASEPRECISIONAllow automatic adjustments to fix invalid polygons
POLYLINC Polygon line increment
POLYSINC Polygon sample increment
NUMVERTICES Polygon steps
MAXEMISSION Maximum emission angle to include in polygon
MAXINCIDENCE Maximum incidence angle to include in polygon

SPICE Option

Name Description
SPICE Run spiceinit on the input

Camera Test

Name Description
VCAMERA Test image center for valid camera

Files: FROM

Description

Input cube with appropriate camera labels (Instrument and kernel groups). This file must be in raw camera space, which is a "level 1" cube.

Type cube
File Mode input
Filter *.cub *.CUB

Files: TO

Description

A text file in label format (PVL) which will contain the results of this program. This file can be used in conjunction with the "getkey" program in order to pass the results to another program when developing scripts.

Type filename
File Mode output
Filter *.txt *.pvl

General Output Options: FORMAT

Description

Specify the Output format type, FLAT or PVL style.

Type string
Default PVL
Option List:
Option Brief Description
PVLCreate PVL output Caminfo data to be generated in PVL format
FLAT Create CSV output Caminfo data to be generated in Comma Separated Value (CSV) format

Exclusions

  • ISISLABEL
  • ORIGINALLABEL
  • POLYGON
  • USELABEL

General Output Options: APPEND

Description

Append caminfo information to existing file. This will append the caminfo data to the filename specified for the TO parameter beginning at a new line.

Type boolean
Default false

General Output Options: GEOMETRY

Description

Get geometry information from the camera at the center of the image. These data are listed under the Geometry Object heading. The keyword/values contained therein are listed here:

Type boolean
Default TRUE

General Output Options: ISISLABEL

Description

This option will extract the ISIS label and write it to the output PVL file.

Type boolean
Default FALSE

General Output Options: ORIGINALLABEL

Description

Include the original labels of the cube in the PVL.

Type boolean
Default FALSE

General Output Options: STATISTICS

Description

Include DN statistics for all bands within the cube. These data are contained in the Statistics object. The keyword/values contained therein are:

Type boolean
Default FALSE

General Output Options: CAMSTATS

Description

Run camstats to get camera information that can be expressed as a range. Camstats will run on the entire cube (common object), and for each band (bandset object). The default linc and sinc for camstats is "1". The user can select a different linc and sinc. Output values are:

Type boolean
Default FALSE
Inclusions
  • SINC
  • LINC

General Output Options: LINC

Description

This is the line increment used by camstats.

Type integer
Default 1
Minimum 1 (inclusive)

General Output Options: SINC

Description

This is the sample increment used by camstats.

Type integer
Default 1
Minimum 1 (inclusive)

Polygon Output Options: USELABEL

Description

Read the footprint blob from the image label instead of creating the footprint.

Type boolean
Default FALSE
Exclusions
  • POLYGON
  • INCTYPE
  • INCREASEPRECISION
  • NUMVERTICES
  • POLYLINC
  • POLYSINC
  • MAXEMISSION
  • MAXINCIDENCE

Polygon Output Options: POLYGON

Description

Use the imagePolygon class to gather polygon information. The output polygon will be in well-known text format (WKT). These data are contained within the Polygon object. The keyword/values contained therein are:

Type boolean
Default FALSE
Exclusions
  • USELABEL
Inclusions
  • INCTYPE
  • INCREASEPRECISION
  • NUMVERTICES
  • POLYLINC
  • POLYSINC
  • MAXEMISSION
  • MAXINCIDENCE

Polygon Output Options: INCTYPE

Description

When true, use NUMVERTICES to set an approximate number of steps for the footprint. Otherwise use POLYLINC and POLYSINC to create the polygon based on the dimensions of the cube.

Type string
Default LINCSINC
Option List:
Option Brief Description
LINCSINC Use POLYLINC and POLYSINC for polygon quality Enable this option to use the number of samples and lines to skip around the perimeter of the image to compute the polygon footprint.

Exclusions

  • NUMVERTICES
VERTICES Use NUMVERTICES for polygon quality Enable this option to use a total number of vertices around the perimeter of the image to compute the polygon footprint.

Exclusions

  • POLYLINC
  • POLYSINC

Polygon Output Options: INCREASEPRECISION

Description

Enabling this option will allow the automatic reduction of the SINC and LINC parameters whenever their current values result in an invalid polygon. In addition, a results group will be created with the keywords SINC/LINC which reveal what SINC/LINC values were actually used for the creation of the footprint. NOTE: This parameter can result in a drastic increase in running time as well as a change to user input values.

Type boolean
Default FALSE

Polygon Output Options: POLYLINC

Description

Specifies the number of lines to skip around the perimeter of the image to compute the polygon footprint. Note that currently, an increment of 1 will not work for pushframe instruments such as THEMIS-VIS.

Type integer
Internal Default 10% of the cube's total lines
Minimum 1 (inclusive)

Polygon Output Options: POLYSINC

Description

Specifies the number of samples to skip around the perimeter of the image to compute the polygon footprint. Note that currently, an increment of 1 will not work for pushframe instruments such as THEMIS-VIS.

Type integer
Internal Default 10% of the cube's total samples
Minimum 1 (inclusive)

Polygon Output Options: NUMVERTICES

Description

Specifies the approximate number of vertices (+/- 3) to take around the image to compute the polygon footprint. (In limb images, the number of steps can be much more or less than 3 off.) Note that currently, an increment of 4 or less will not work for pushframe instruments such as THEMIS-VIS.

Type integer
Default 40
Minimum 4 (inclusive)

Polygon Output Options: MAXEMISSION

Description

Specifies the maximum emission angle that a polygon point is allowed to have. This limit is useful for eliminating limb data that cause numerous ragged spikes. Limb data will generally result in odd polygon footprints as the geometry becomes unstable at the limb due to obliqueness particularly when using a DEM for the shape model (see spiceinit). This parameter restricts the emission angle to create better behaved polygons at the limb while sacrificing some (very oblique) data.

Note: For images that have been run through spiceinit with a DEM, the emission angle range may need to be decreased. This will avoid the instability that occurs at the limb and will avoid spiking of the data.

Type double
Default 89.5

Polygon Output Options: MAXINCIDENCE

Description

Specifies the maximum incidence angle that a polygon point is allowed to have. This limit is useful for eliminating terminator data that will typically be lost in photometric corrections. This parameter restricts the incidence angle to create more data relevant polygons at the terminator while sacrificing some (non-photometric) data.

Type double
Default 120.0

SPICE Option: SPICE

Description

If the user sets this to true then the spiceinit program will be run on the input file. Spiceinit will use the system SPICE kernels, so any updates to SPICE information will be lost. Spiceinit is in this program to facilitate UPC processing.

Type boolean
Default FALSE

Camera Test: VCAMERA

Description

If the user sets this parameter to true, a test will determine if a valid camera can be created at the center of the image band. If a valid camera cannot be created the program will end. The default is to output any available information without testing the camera.

Type boolean
Default FALSE

History

Robert Sucharski2007-04-10 Original version
Steven Lambright2007-08-10 Added an application test
Steven Koechle2007-11-01 Fixed WKT calls
Tracie Sucharski2007-11-09 Remove ToWKT calls and PolygonTools.h inclusion. The geos package now has a method to return a WKT string, so the ToWKT method has been removed from the PolygonTools class.
Kris Becker2007-12-07 Made the following modifications: fixed typo in PercentNull and MaximumLongitude keywords; use the base file name for generation of temporary files to further ensure uniqueness; run camstats once if there is only one band - doubles execution speed for single band images when CAMSTATS option is used; substitute the NULL string for all special pixel values; added corner pixel keywords for PDS compatibility; added phase, emission, incidence angles and line and sample pixel resolution at the center pixel; added test for intersection of longitude domain, north and south poles and keywords that report them; added option to output ISIS cube labels; corrected computations for parallax and shadow keywords.
Kris Becker2007-12-19 Renamed the HasLongitudeDomain keyword to HasLongitudeBoundary. Makes more sense.
Kris Becker2008-02-27 Corrected method call to compute polygon with proper parameters as well as correct band number. Added code to better honor specific cube attributes (such as band numbers) in computations. Also will produce NULL valued keywords where NULLs are a produced instead of the real value for the ISIS NULL pixel value.
Steven Lambright2008-05-12 Removed references to CubeInfo
Bob Sucharski2008-07-31 Added Camera Test option to test for a valid camera at center of image and return an error and end if a valid camera cannot be created.
Kris Becker2008-09-22 Reworked the output PVL format; added more keywords to the Common object that indicate versions and dates; added more values to Geometry and Polygon object.
Kris Becker2008-10-22 Corrected generation of polygon for multi-band data. It created a POLYGON union instead of the required MULTIPOLYGON.
Kris Becker2008-10-30 The target center distance and subspacecraft latitude were not properly propagated to the output PVL file and consequently were invalid. This has been corrected.
Kris Becker2008-12-29 Added RightAscension, Declination, SubSolarGroundAzimuth, and SubSpacecraftGroundAzimuth computations; added center line/sample image coordinate used to compute center geometry; added check of valid image line/sample coordinates when testing for north/south poles (some camera models return valid states when coordinates are outside of image boundaries).
Kris Becker2009-02-26 Modified to actually exclude the unconditional computation of the image polygon to assist in some geometry values. It is no longer computed if the user does not select the POLYGON option. The implications of this are that some of the keywords in the output Geometry group are no longer ever relevant. These keywords were all moved to the Polygon group. These keywords are: CentroidLine, CentroidSample, CentroidLatitude, CentroidLongitude, CentroidRadius and SurfaceArea. User will no longer see these values if the POLYGON option is not selected. Also the Radius keyword in the Polygon group has been removed as it is redundant with CentroidRadius.
Kris Becker2009-05-29 Added PIXINC parameter to allow user to specify number of pixels to skip around the perimeter of the image to compute the polygon.
Kris Becker2009-05-29 Fixed bug where image was a 0 longitude boundary crosser. It would typically fail when determining centroid information unless converted to 180 domain. This will also be used at the poles as it seems to work better in the 180 domain as well. (This process projects the footprint to a Sinusoidal projection to determine area which requires an equal area projection, such as Sinusoidal.)
Kris Becker2009-07-08 Added the MAXEMISSION and MAXINCIDENCE limit parameters to better control limb and terminator polygon generation.
Kris Becker2009-08-24 Allow disabling of shape model use when constructing polygons that contain limbs.
Mackenzie Boyd2010-06-14 Removed polygon options group and placed the options within output options. Added inclusion for parameters related to polygons to only be available when polygons are selected. Made TO option not have a default of None, updated documentation and modified formatting.
Jai Rideout2011-02-17 Replaced PIXINC with POLYSINC and POLYLINC. Renamed SINC and LINC to STATSSINC and STATSLINC.
Sharmila Prasad2011-02-24 Added option for the output file to be in CSV format and also ability to append to the existing output file.
Jai Rideout2011-03-01 Renamed STATSSINC and STATSLINC back to SINC and LINC.
Sharmila Prasad2011-03-02 Fix App tests and add header for flat file if file does not exist.
Jai Rideout2011-03-03 Fixed incorrect CSV output format.
Christopher Austin2011-03-18 Rewrote the entire application to no longer have hard-coded values for CSV, including the removal of duplicated code, updated includes, and corrected the CSV to display the same values as the PVL does.
Christopher Austin2011-03-18 Added new parameters including FLATINC.
Christopher Austin2011-03-22 Changed the new parameter's names. (INCTYPE, NUMVERTICES)
Christopher Austin2011-05-12 Added smarts to the VERTICES option.
Travis Addair2011-07-27 Added INCREASEPRECISION option for creating an Image Polygon, the same one as used by "footprintinit".
Kris Becker2012-11-23 The computation of ParallaxX/ParallaxY and ShadowX/ShadowY values was not properly implemented. Updated documentation with a new example. Fixes #1296.
Janet Barrett2013-01-29 Added the USELABEL option. This will allow the user to request that the footprint be read from the labels of the input image file rather than regenerating the footprint. Fixes #1452.
Janet Richie2013-02-25 Reviewed documentation. References #1452.