Home
About ISIS
Support
Download

ISIS 3

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents
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.7.0  | 2019-04-16"
    RunDate     = 2019-04-24T23:29:22
    IsisId      = MeSSEnGeR/MDIS-WAC/1/0211286081:889000
    From        = EW0211286081G.lev1.cub
    Lines       = 1024
    Samples     = 1024
    Bands       = 1
  End_Object

  Object = Camstats
    MinimumLatitude           = 46.17349725649
    MaximumLatitude           = 54.072584907617
    MinimumLongitude          = 284.17017788557
    MaximumLongitude          = 296.47498126014
    MinimumResolution         = 235.10973750118
    MaximumResolution         = 238.32543228025
    MinimumPhase              = 50.107674499885
    MaximumPhase              = 60.748154060087
    MinimumEmission           = 0.0076793870352429
    MaximumEmission           = 11.494912087698
    MinimumIncidence          = 52.486663651971
    MaximumIncidence          = 58.235714475896
    LocalTimeMinimum          = 9.7555337547863
    LocalTimeMaximum          = 10.575853979758
    ObliqueResolutionMinimum = 235.23505597394
    ObliqueResolutionMaximum  = 243.18035398447
  End_Object

  Object = Geometry
    BandsUsed                  = 1
    ReferenceBand              = 1
    OriginalBand               = 1
    Target                     = Mercury
    StartTime                  = 2011-04-14T16:30:13.6376399
    EndTime                    = 2011-04-14T16:30:13.6376399
    CenterLine                 = 512.0
    CenterSample               = 512.0
    CenterLatitude             = 50.134547680289
    CenterLongitude            = 290.41254981797
    CenterRadius               = 2437088.6898077
    RightAscension             = 159.91342230848
    Declination                = -41.672357224345
    UpperLeftLongitude         = 291.64523858807
    UpperLeftLatitude          = 54.072584907617
    LowerLeftLongitude         = 284.17017788557
    LowerLeftLatitude          = 50.690335603589
    LowerRightLongitude        = 289.36443784287
    LowerRightLatitude         = 46.17349725649
    UpperRightLongitude        = 296.47498126014
    UpperRightLatitude         = 49.243965896632
    PhaseAngle                 = 55.329415379509
    EmissionAngle              = 0.13392142633291
    IncidenceAngle             = 55.328513822534
    NorthAzimuth               = 214.59793748861
    OffNadir                   = 0.086941089750923
    SolarLongitude             = 187.03600434339
    LocalTime                  = 10.171691883613
    TargetCenterDistance       = 3754.0157644796
    SlantDistance              = 1316.9294100772
    SampleResolution           = 235.52868468741
    LineResolution             = 235.52868468741
    PixelResolution            = 235.52868468741
    MeanGroundResolution       = 236.93804115469
    SubSolarAzimuth            = 0.5352090657949
    SubSolarGroundAzimuth      = 145.94153132534
    SubSolarLatitude           = -0.0041617302711888
    SubSolarLongitude          = 317.83717156377
    SubSpacecraftAzimuth       = 270.19620722977
    SubSpacecraftGroundAzimuth = 55.602129115968
    SubSpacecraftLatitude      = 50.16107286585
    SubSpacecraftLongitude     = 290.47306057538
    ParallaxX                  = -0.0013204675649152
    ParallaxY                  = 0.0019286479781325
    ShadowX                    = 1.197730691686
    ShadowY                    = 0.80965910389868
    HasLongitudeBoundary       = FALSE
    HasNorthPole               = FALSE
    HasSouthPole               = FALSE
    ObliqueSampleResolution    = 235.52932807053
    ObliqueLineResolution      = 235.52932807053
    ObliquePixelResolution     = 235.52932807053
    ObliqueDetectorResolution  = 235.52932807053
  End_Object

  Object = Polygon
    CentroidLine      = 515.54847960298
    CentroidSample    = 516.98396885203
    CentroidLatitude  = 50.100681689843
    CentroidLongitude = 290.41177111088
    CentroidRadius    = 2437182.1999165 <meters>
    SurfaceArea       = 58449.84444296 <km^2>
    GlobalCoverage    = 0.078306 <percent>
    SampleIncrement   = 102
    LineIncrement     = 102
    GisFootprint      = "MULTIPOLYGON (((291.6490765146723447
                         54.0741794093634311, 292.1787510717393275
                         53.6050947627796290, 292.6939712762379031
                         53.1280214945194871, 293.1935996155742714
                         52.6462518066594427, 293.6877586602358861
                         52.1686313743837218, 294.1686076850560312
                         51.6877577856796790, 294.6441807247810516
                         51.2069352955664527, 295.1120304970848451
                         50.7239436351535318, 295.5723044120834970
                         50.2383991133846095, 296.0235675535569158
                         49.7502507245209387, 296.4656892412461389
                         49.2598280749686097, 296.4772543488990664
                         49.2415935246169241, 295.7234802633013828
                         48.9577284467905898, 294.9804685531953510
                         48.6694912257124912, 294.2522098029692188
                         48.3747622755557956, 293.5281508420213754
                         48.0783235834621792, 292.8180445861410703
                         47.7741872572646500, 292.1158965526823295
                         47.4656099909531335, 291.4221991088060690
                         47.1514387416925160, 290.7360673250992136
                         46.8330969718050980, 290.0574985212423371
                         46.5087223303417048, 289.3864267339227467
                         46.1811141464289676, 289.3612293705994034
                         46.1717876266695484, 288.8840625555773158
                         46.6333914182544547, 288.3997485195988020
                         47.0942608584519604, 287.9056077359897472
                         47.5502843497149215, 287.4038483357975338
                         48.0050803855386121, 286.8940363669749445
                         48.4575332864047326, 286.3728157777912884
                         48.9061755371698297, 285.8404968421083368
                         49.3521091874764650, 285.2987408366519162
                         49.7958568236399373, 284.7458938243490820
                         50.2370818707379030, 284.1837853403296208
                         50.6757005534934777, 284.1672379981782228
                         50.6924300136348975, 284.8660019234981746
                         51.0492008969251785, 285.5767712367713216
                         51.4009577885800155, 286.2937518600310227
                         51.7489227234357969, 287.0217082812425247
                         52.0921982632441569, 287.7605440724607888
                         52.4305033881260769, 288.5087072424007033
                         52.7652722844764526, 289.2682486994754072
                         53.0953120132625287, 290.0385615025346056
                         53.4251525926730508, 290.8227840059549862
                         53.7506798361148057, 291.6190588029043624
                         54.0657945141910190, 291.6490765146723447
                         54.0741794093634311)))"

    Group = Mapping
      TargetName         = Mercury
      EquatorialRadius   = 2439400.0 <meters>
      PolarRadius        = 2439400.0 <meters>
      LatitudeType       = Planetocentric
      LongitudeDirection = PositiveEast
      LongitudeDomain    = 360
      MinimumLatitude    = 46.169577318305
      MaximumLatitude    = 54.076352727416
      MinimumLongitude   = 284.16397198204
      MaximumLongitude   = 296.48085203894
      PixelResolution    = 235.54475872549
      ProjectionName     = Sinusoidal
      CenterLongitude    = 290.41254981797
    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, SubSolarAzimuth, ObliqueLineResolution, ObliqueSampleResolution, ObliquePixelResolution, and ObliqueDetectorResolution

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.
Kaitlyn Lee2019-04-22 Added oblique sample, line, detector, and pixel resolutions to the geometry PVL group. Updated example output in application description so that the addded oblique elements are included. Fixes #2205.