oiGet

Get properties and derived quantities from an optical image structure

     val = oiGet(oi,parm,varargin)

  Optical image parameters are stored in a structure. Some parameters are
  stored directly, others are calculated from  the data structure.  We
  store the unique values and  calculate many derived values. 

  The optical image structures are stored in a cell array, vcSESSION.OPTICALIMAGE{}

  To retrieve the currently selected optical image, use either
     [val, oi] = vcGetSelectedObject('OI');
     oi = vcGetObject('OI');

  A '*' indicates that the syntax sceneGet(scene,param,unit) can be used, where
  unit specifies the spatial scale of the returned value:  'm', 'cm', 'mm',
  'um', 'nm'.  Default is meters ('m').

 Examples:
    oiGet(oi,'rows')
    oiGet(oi,'wave')
    oiGet(oi,'optics')
    oiGet(oi,'area','mm')
    oiGet(oi,'wres','microns')
    oiGet(oi,'angularresolution')
    oiGet(oi,'distPerSamp','mm')
    oiGet(oi,'spatialsupport','microns')

  General properties
      {'name'}           - optical image name
      {'type'}           - 'opticalimage'
      {'filename'}       - if read from a file, could store here
      {'consistency'}    - the oiWindow display reflects the current state (1) or not (0).
      {'rows'}           - number of row samples
      {'cols'}           - number of col samples
      {'size'}           - rows,cols
      {'imagedistance'}  - distance from lens to image, negative
      {'hfov'}           - horizontal field of view (deg)
      {'vfov'}           - vertical field of view (deg)
      {'aspectratio'}    - aspect ratio of image
      {'height'}*        - image height
      {'width'}*         - image width
      {'diagonal'}*      - image diagonal length
      {'heightandwidth'}*- (height,width)
      {'area'}*          - optical image area
      {'centerpixel'}    - (row,col) of point at center of image

 Irradiance
      {'data'}          - Data structure
        {'photons'}     - Irradiance data
        {'datamax'}     - Used for compression, not for general users
        {'datamin''}    - Used for compression, not for general users
        {'bitdepth''}   - Used for compression, not for general users
        {'energy'}      - Energy rather than photon representation
        {'meanilluminance'}  - Mean illuminance
        {'illuminance'}      - Spatial array of optical image illuminance

 Wavelength information
      {'spectrum'}     - Wavelength information structure
        {'binwidth'}   - spacing between samples
        {'wave'}       - wavelength samples (nm)
        {'nwave'}      - number of wavelength samples

 Resolution
      {'hspatialresolution'}*   - height spatial resolution
      {'wspatialresolution'}*   - width spatial resolution    
      {'samplespacing'}*       - (width, height) spatial resolution
      {'distancepersample'}*   - (row,col) distance per spatial sample
      {'distanceperdegree'}*   - Distance per degree of visual angle
      {'degreesperdistance'}*
      {'spatialsamplingpositions'}*   - Spatial locations of points
      {'hangularresolution'}     - angular degree per pixel in height
      {'wangularresolution'}     - angular degree per pixel in width
      {'angularresolution'}      - (height,width) angular resolutions
      {'frequencysupport'}*      - frequency resolution in cyc/deg or
            lp/Unit, i.e., cycles/{meters,mm,microns}
            oiGet(oi,'frequencyResolution','mm')
      {'maxfrequencyresolution'}* - Highest frequency
            oiGet(oi,'maxFrequencyResolution','um')
      {'frequencysupportcol','fsupportx'}*  - Frequency support for cols
      {'frequencysupportrow','fsupporty'}*  - Frequency support for rows

 Optics information
      {'optics'}           - See opticsSet/Get


 Copyright ImagEval Consultants, LLC, 2003.