AreaFile (cdm-mcidas 5.2.0 API)

java.lang.Object
- ucar.mcidas.AreaFile

All Implemented Interfaces:

Serializable
```
public class AreaFile
extends Object
implements Serializable
```
AreaFile interface with McIDAS 'area' file format image data.
This will allow 'area' format data to be read from disk; the navigation block is made available (see GVARnav for example).

Calibration is handled via classes that implement the Calibrator interface.

This implementation does not check the 'valcode' on each line.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`AD_AUXOFFSET` AD_AUXOFFSET - byte offset to start of auxilliary data section
`static int`	`AD_AVGSMPFLAG` AD_AVGSMPFLAG - data is averaged (1), or sampled (0)
`static int`	`AD_BANDMAP` AD_BANDMAP - spectral band map, bit set for each of 32 bands present
`static int`	`AD_CALLENGTH` AD_CALLENGTH - length in bytes of line prefix calibration information
`static int`	`AD_CALOFFSET` AD_CALOFFSET - byte offset to start of calibration section
`static int`	`AD_CALTYPE` AD_CALTYPE - McIDAS calibration type (ascii, satellite specific)
`static int`	`AD_CALTYPESCALE` AD_CALTYPESCALE - calibration scaling factor
`static int`	`AD_CALTYPEUNIT` AD_CALTYPEUNIT - calibration unit
`static int`	`AD_CRDATE` AD_CRDATE - year and day image was created, CCYYDDD format
`static int`	`AD_CRTIME` AD_CRTIME - time image was created, HHMMSS format
`static int`	`AD_DATAOFFSET` AD_DATAOFFSET - byte offset to start of data block
`static int`	`AD_DATAWIDTH` AD_DATAWIDTH - number of bytes per data point
`static int`	`AD_DIRSIZE` AD_DIRSIZE - size in 4 byte words of an image directory block
`static int`	`AD_DOCLENGTH` AD_DOCLENGTH - length in bytes of line prefix documentation
`static int`	`AD_ELEMRES` AD_ELEMRES - data resolution in element direction
`static int`	`AD_IMGDATE` AD_IMGDATE - nominal year and day of the image, YYYDDD format
`static int`	`AD_IMGTIME` AD_IMGTIME - nominal time of the image, HHMMSS format
`static int`	`AD_LEVLENGTH` AD_LEVLENGTH - length in bytes of line prefix level section
`static int`	`AD_LINERES` AD_LINERES - data resolution in line direction
`static int`	`AD_NAVOFFSET` AD_NAVOFFSET - byte offset to start of navigation block
`static int`	`AD_NUMBANDS` AD_NUMBANDS - number of spectral bands, or channels, in image
`static int`	`AD_NUMCOMMENTS` AD_NUMCOMMENTS - number of 80 character comment cards
`static int`	`AD_NUMELEMS` AD_NUMELEMS - number of data points per line
`static int`	`AD_NUMLINES` AD_NUMLINES - number of lines in the image
`static int`	`AD_PFXSIZE` AD_PFXSIZE - length in bytes of line prefix section
`static int`	`AD_PROJNUM` AD_PROJNUM - SSEC project number used in creating image
`static int`	`AD_SENSORID` AD_SENSORID - McIDAS sensor identifier
`static int`	`AD_SRCTYPE` AD_SRCTYPE - McIDAS source type (ascii, satellite specific)
`static int`	`AD_SRCTYPEORIG` AD_SRCTYPEORIG - original source type (ascii, satellite specific)
`static int`	`AD_STARTDATE` AD_STARTDATE - actual image start year and Julian day, yyyddd format
`static int`	`AD_STARTSCAN` AD_STARTSCAN - starting scan number (sensor based) of image
`static int`	`AD_STARTTIME` AD_STARTTIME - actual image start time, hhmmss; in milliseconds for POES data
`static int`	`AD_STATUS` AD_STATUS - old status field, now used as position num in ADDE
`static int`	`AD_STELEM` AD_STELEM - upper left image element coordinate
`static int`	`AD_STLINE` AD_STLINE - upper left image line coordinate
`static int`	`AD_VALCODE` AD_VALCODE - validity code
`static int`	`AD_VERSION` AD_VERSION - McIDAS area file format version number
`static int`	`VERSION_NUMBER` VERSION_NUMBER - version number for a valid AREA file (since 1985)

Constructor Summary

Constructors
Constructor and Description
`AreaFile(String source)` Creates an AreaFile object that allows reading of McIDAS 'area' file format image data.
`AreaFile(String source, int startLine, int numLines, int lineMag, int startElem, int numEles, int eleMag, int band)` Create a subsetted instance.
`AreaFile(URL url)` create an `AreaFile` that allows reading of McIDAS 'area' file format image data from a `URL` with a protocol of either `file` or `ADDE`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`close()` Close this instance.
`AreaDirectory`	`getAreaDirectory()` Returns the AreaDirectory object for this AreaFile
`int[]`	`getAux()` Returns AUX block
`int[]`	`getCal()` Returns calibration block
`int`	`getCalType()` Get the calibration type that will be used on data returned form `getCalibratedData()`.
`int[][][]`	`getData()` Read the AREA data.
`int[][][]`	`getData(int[][][] target)` Read AREA file data by reference.
`int[][]`	`getData(int lineNumber, int eleNumber, int numLines, int numEles)` Deprecated. Use one of the factory methods from `AreaFileFactory` with the appropriate subsetting parameters.
`int[][]`	`getData(int lineNumber, int eleNumber, int numLines, int numEles, int bandNumber)` Deprecated. Use one of the factory methods from `AreaFileFactory` with the appropriate subsetting parameters.
`int[]`	`getDir()` Returns the directory block
`float[][][]`	`getFloatData()` Read the AREA file and return the contents as floats.
`String`	`getImageSource()` returns the string of the image source location
`int[]`	`getNav()` Returns the navigation block
`AREAnav`	`getNavigation()` Get the navigation, and pre-set it for the ImageStart and Res (from Directory block), and the file start (0,0), and Mag (1,1).
`boolean`	`isRemote()` Was this instance create with a remote data source.
`boolean`	`isSubsetted()` Is this `AreaFile` instance subseted.
`static boolean`	`isURLHandlerLoaded()`
`static void`	`main(String[] args)` Test Method.
`void`	`save(String outputFile)` Save this AreaFile to the output location
`void`	`save(String outputFile, boolean verbose)` Save this AreaFile to the output location
`void`	`setCalType(int cal)` Set the calibration type that will be used on data returned from `getCalibratedData()`.
`String`	`toString()` Get a String representation of this image metadata/information

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - AD_STATUS
```
public static final int AD_STATUS
```
    AD_STATUS - old status field, now used as position num in ADDE
    
    See Also:
    
    Constant Field Values
  - AD_VERSION
```
public static final int AD_VERSION
```
    AD_VERSION - McIDAS area file format version number
    
    See Also:
    
    Constant Field Values
  - AD_SENSORID
```
public static final int AD_SENSORID
```
    AD_SENSORID - McIDAS sensor identifier
    
    See Also:
    
    Constant Field Values
  - AD_IMGDATE
```
public static final int AD_IMGDATE
```
    AD_IMGDATE - nominal year and day of the image, YYYDDD format
    
    See Also:
    
    Constant Field Values
  - AD_IMGTIME
```
public static final int AD_IMGTIME
```
    AD_IMGTIME - nominal time of the image, HHMMSS format
    
    See Also:
    
    Constant Field Values
  - AD_STLINE
```
public static final int AD_STLINE
```
    AD_STLINE - upper left image line coordinate
    
    See Also:
    
    Constant Field Values
  - AD_STELEM
```
public static final int AD_STELEM
```
    AD_STELEM - upper left image element coordinate
    
    See Also:
    
    Constant Field Values
  - AD_NUMLINES
```
public static final int AD_NUMLINES
```
    AD_NUMLINES - number of lines in the image
    
    See Also:
    
    Constant Field Values
  - AD_NUMELEMS
```
public static final int AD_NUMELEMS
```
    AD_NUMELEMS - number of data points per line
    
    See Also:
    
    Constant Field Values
  - AD_DATAWIDTH
```
public static final int AD_DATAWIDTH
```
    AD_DATAWIDTH - number of bytes per data point
    
    See Also:
    
    Constant Field Values
  - AD_LINERES
```
public static final int AD_LINERES
```
    AD_LINERES - data resolution in line direction
    
    See Also:
    
    Constant Field Values
  - AD_ELEMRES
```
public static final int AD_ELEMRES
```
    AD_ELEMRES - data resolution in element direction
    
    See Also:
    
    Constant Field Values
  - AD_NUMBANDS
```
public static final int AD_NUMBANDS
```
    AD_NUMBANDS - number of spectral bands, or channels, in image
    
    See Also:
    
    Constant Field Values
  - AD_PFXSIZE
```
public static final int AD_PFXSIZE
```
    AD_PFXSIZE - length in bytes of line prefix section
    
    See Also:
    
    Constant Field Values
  - AD_PROJNUM
```
public static final int AD_PROJNUM
```
    AD_PROJNUM - SSEC project number used in creating image
    
    See Also:
    
    Constant Field Values
  - AD_CRDATE
```
public static final int AD_CRDATE
```
    AD_CRDATE - year and day image was created, CCYYDDD format
    
    See Also:
    
    Constant Field Values
  - AD_CRTIME
```
public static final int AD_CRTIME
```
    AD_CRTIME - time image was created, HHMMSS format
    
    See Also:
    
    Constant Field Values
  - AD_BANDMAP
```
public static final int AD_BANDMAP
```
    AD_BANDMAP - spectral band map, bit set for each of 32 bands present
    
    See Also:
    
    Constant Field Values
  - AD_DATAOFFSET
```
public static final int AD_DATAOFFSET
```
    AD_DATAOFFSET - byte offset to start of data block
    
    See Also:
    
    Constant Field Values
  - AD_NAVOFFSET
```
public static final int AD_NAVOFFSET
```
    AD_NAVOFFSET - byte offset to start of navigation block
    
    See Also:
    
    Constant Field Values
  - AD_VALCODE
```
public static final int AD_VALCODE
```
    AD_VALCODE - validity code
    
    See Also:
    
    Constant Field Values
  - AD_STARTDATE
```
public static final int AD_STARTDATE
```
    AD_STARTDATE - actual image start year and Julian day, yyyddd format
    
    See Also:
    
    Constant Field Values
  - AD_STARTTIME
```
public static final int AD_STARTTIME
```
    AD_STARTTIME - actual image start time, hhmmss; in milliseconds for POES data
    
    See Also:
    
    Constant Field Values
  - AD_STARTSCAN
```
public static final int AD_STARTSCAN
```
    AD_STARTSCAN - starting scan number (sensor based) of image
    
    See Also:
    
    Constant Field Values
  - AD_DOCLENGTH
```
public static final int AD_DOCLENGTH
```
    AD_DOCLENGTH - length in bytes of line prefix documentation
    
    See Also:
    
    Constant Field Values
  - AD_CALLENGTH
```
public static final int AD_CALLENGTH
```
    AD_CALLENGTH - length in bytes of line prefix calibration information
    
    See Also:
    
    Constant Field Values
  - AD_LEVLENGTH
```
public static final int AD_LEVLENGTH
```
    AD_LEVLENGTH - length in bytes of line prefix level section
    
    See Also:
    
    Constant Field Values
  - AD_SRCTYPE
```
public static final int AD_SRCTYPE
```
    AD_SRCTYPE - McIDAS source type (ascii, satellite specific)
    
    See Also:
    
    Constant Field Values
  - AD_CALTYPE
```
public static final int AD_CALTYPE
```
    AD_CALTYPE - McIDAS calibration type (ascii, satellite specific)
    
    See Also:
    
    Constant Field Values
  - AD_AVGSMPFLAG
```
public static final int AD_AVGSMPFLAG
```
    AD_AVGSMPFLAG - data is averaged (1), or sampled (0)
    
    See Also:
    
    Constant Field Values
  - AD_SRCTYPEORIG
```
public static final int AD_SRCTYPEORIG
```
    AD_SRCTYPEORIG - original source type (ascii, satellite specific)
    
    See Also:
    
    Constant Field Values
  - AD_CALTYPEUNIT
```
public static final int AD_CALTYPEUNIT
```
    AD_CALTYPEUNIT - calibration unit
    
    See Also:
    
    Constant Field Values
  - AD_CALTYPESCALE
```
public static final int AD_CALTYPESCALE
```
    AD_CALTYPESCALE - calibration scaling factor
    
    See Also:
    
    Constant Field Values
  - AD_AUXOFFSET
```
public static final int AD_AUXOFFSET
```
    AD_AUXOFFSET - byte offset to start of auxilliary data section
    
    See Also:
    
    Constant Field Values
  - AD_CALOFFSET
```
public static final int AD_CALOFFSET
```
    AD_CALOFFSET - byte offset to start of calibration section
    
    See Also:
    
    Constant Field Values
  - AD_NUMCOMMENTS
```
public static final int AD_NUMCOMMENTS
```
    AD_NUMCOMMENTS - number of 80 character comment cards
    
    See Also:
    
    Constant Field Values
  - AD_DIRSIZE
```
public static final int AD_DIRSIZE
```
    AD_DIRSIZE - size in 4 byte words of an image directory block
    
    See Also:
    
    Constant Field Values
  - VERSION_NUMBER
```
public static final int VERSION_NUMBER
```
    VERSION_NUMBER - version number for a valid AREA file (since 1985)
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - AreaFile
```
public AreaFile(String source)
         throws AreaFileException
```
    Creates an AreaFile object that allows reading of McIDAS 'area' file format image data. allows reading either from a disk file, or a server via ADDE.
    
    Parameters:
    
    source - the file name, ADDE URL, or local file URL to read from
    
    Throws:
    
    AreaFileException - if file cannot be opened
  - AreaFile
```
public AreaFile(URL url)
         throws AreaFileException
```
    create an AreaFile that allows reading of McIDAS 'area' file format image data from a URL with a protocol of either file or ADDE. See adde.AddeURLConnection for more information on constructing ADDE urls.
    
    Parameters:
    
    url -
    
    Throws:
    
    AreaFileException - if file cannot be opened
  - AreaFile
```
public AreaFile(String source,
                int startLine,
                int numLines,
                int lineMag,
                int startElem,
                int numEles,
                int eleMag,
                int band)
         throws AreaFileException
```
    Create a subsetted instance. When subsetted, the data not included in the subset is no longer available to this instance due to the directory block being updated with the subsetting parameters.
    Parameters:
    
    source - the path to the file
    
    startLine - the starting image line
    
    numLines - the total number of lines to return
    
    lineMag - the line magnification. Valid values are <= -1. -1, 0, and 1 are all taken to be full line resolution, -2 is every other line, -3 every third, etc...
    
    startElem - the starting image element
    
    numEles - the total number of elements to return
    
    eleMag - the element magnification. Valid values are <= -1. -1, 0, and 1 are all taken to be full element resolution, -2 is every other element, -3 every third, etc...
    
    band - the 1-based band number for the subset, which must be present in the directory blocks band map or -1 for the first band
    
    Throws:
    
    AreaFileException - if file cannot be opened
    IllegalArgumentException - If the magnification is greater than 1, the band number is not in the band map, or either of the following are true:
    startLine + (numLines * abs(lineMag)) > total number of lines startElem + (numEles * abs(eleMag)) > total number of elements
- Method Detail
  - isURLHandlerLoaded
```
public static boolean isURLHandlerLoaded()
```
    Returns:
    
    status
  - isSubsetted
```
public boolean isSubsetted()
```
    Is this AreaFile instance subseted.
    
    Returns:
    
    True if this instance represents a subset of the total data available.
  - isRemote
```
public boolean isRemote()
```
    Was this instance create with a remote data source.
    
    Returns:
    
    True if created with an ADDE url
  - getImageSource
```
public String getImageSource()
```
    returns the string of the image source location
    
    Returns:
    
    name of image source
  - getDir
```
public int[] getDir()
```
    Returns the directory block
    
    Returns:
    
    an integer array containing the area directory
  - getAreaDirectory
```
public AreaDirectory getAreaDirectory()
```
    Returns the AreaDirectory object for this AreaFile
    
    Returns:
    
    AreaDirectory
  - getNav
```
public int[] getNav()
```
    Returns the navigation block
    
    Returns:
    
    an integer array containing the nav block data
  - getNavigation
```
public AREAnav getNavigation()
                      throws AreaFileException
```
    Get the navigation, and pre-set it for the ImageStart and Res (from Directory block), and the file start (0,0), and Mag (1,1).
    
    Returns:
    
    AREAnav for this image (may be null)
    
    Throws:
    
    AreaFileException
  - getCal
```
public int[] getCal()
```
    Returns calibration block
    
    Returns:
    
    an integer array containing the nav block data
  - getAux
```
public int[] getAux()
```
    Returns AUX block
    
    Returns:
    
    an integer array containing the aux block data
  - getData
```
public int[][][] getData()
                  throws AreaFileException
```
    Read the AREA data.
    
    Returns:
    
    int array[band][lines][element] - If the AreaFile was created as a subset only the band and subset indicated are returned, otherwise all bands are returned.
    
    Throws:
    
    AreaFileException - if there is a problem
  - getData
```
public int[][][] getData(int[][][] target)
                  throws AreaFileException
```
    Read AREA file data by reference. After reading the internal data array is will be a reference to the target array, so any changes made to the target array will be reflected in the internal data array.
    
    Parameters:
    
    target - Array to use as the destination of the data read. This array must be appropriately dimensioned as [#bands][#lines][#elems].
    
    Returns:
    
    int array[band][lines][element] - If the AreaFile was created as a subset only the band and subset indicated are returned, otherwise all bands are returned.
    
    Throws:
    
    IllegalArgumentException - If the target array is not dimensioned according to the subset, if subsetted, or otherwise has dimensions other than [bands][lines][elements].
    
    AreaFileException - If an error occurs while reading data.
  - setCalType
```
public void setCalType(int cal)
```
    Set the calibration type that will be used on data returned from getCalibratedData(). This must be called before getCalibratedData() to get calibrated data, otherwise it will just return the data in the format specified in the directory.
    
    Parameters:
    
    cal - calibration type from Calibrator.
  - getCalType
```
public int getCalType()
```
    Get the calibration type that will be used on data returned form getCalibratedData().
    
    Returns:
    
    calibration type from Calibrator.
  - getFloatData
```
public float[][][] getFloatData()
                         throws AreaFileException
```
    Read the AREA file and return the contents as floats. If the calibration type has been set via setCalType(), isRemote() is false, and a Calibrator is available data is calibrated before returning, otherwise the calibration type is ignored. The original data is alway preserved.
    
    Returns:
    
    data[band][lines][elements] as described above
    
    Throws:
    
    AreaFileException - on error reading data.
    
    See Also:
    
    Calibrator
  - getData
```
public int[][] getData(int lineNumber,
                       int eleNumber,
                       int numLines,
                       int numEles)
                throws AreaFileException
```
    Deprecated. Use one of the factory methods from AreaFileFactory with the appropriate subsetting parameters.
    
    Read the specified 2-dimensional array of data values from the AREA file. Values will always be returned as int regardless of whether they are 1, 2, or 4 byte values.
    
    Parameters:
    
    lineNumber - the file-relative image line number that will be put in array[0][j]
    
    eleNumber - the file-relative image element number that will be put into array[i][0]
    
    numLines - the number of lines to return
    
    numEles - the number of elements to return for each line
    
    Returns:
    
    int array[lines][elements] with data values.
    
    Throws:
    
    AreaFileException - if the is a problem reading the file
  - getData
```
public int[][] getData(int lineNumber,
                       int eleNumber,
                       int numLines,
                       int numEles,
                       int bandNumber)
                throws AreaFileException
```
    Deprecated. Use one of the factory methods from AreaFileFactory with the appropriate subsetting parameters.
    
    Read the specified 2-dimensional array of data values from the AREA file. Values will always be returned as int regardless of whether they are 1, 2, or 4 byte values.
    
    Parameters:
    
    lineNumber - the file-relative image line number that will be put in array[0][j]
    
    eleNumber - the file-relative image element number that will be put into array[i][0]
    
    numLines - the number of lines to return
    
    numEles - the number of elements to return for each line
    
    bandNumber - the spectral band to return
    
    Returns:
    
    int array[lines][elements] with data values.
    
    Throws:
    
    AreaFileException - if the is a problem reading the file
  - toString
```
public String toString()
```
    Get a String representation of this image metadata/information
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    string of metadata
  - main
```
public static void main(String[] args)
                 throws Exception
```
    Test Method.
```
 USAGE: AreaFile <source> [(raw|temp|brit|rad|refl)]
 
```
    If source is a file path or url without subsetting information directory information is printed. If source is a local file url with subsetting information data is printed according to the parameters.
    
    This has not been tested with an ADDE url, but it should work ... maybe.
    Parameters:
    
    args -
    
    Throws:
    
    Exception
  - close
```
public void close()
```
    Close this instance.
  - save
```
public void save(String outputFile)
          throws AreaFileException
```
    Save this AreaFile to the output location
    
    Parameters:
    
    outputFile - path to the output file
    
    Throws:
    
    AreaFileException - problem saving to the file
  - save
```
public void save(String outputFile,
                 boolean verbose)
          throws AreaFileException
```
    Save this AreaFile to the output location
    
    Parameters:
    
    outputFile - path to the output file
    
    verbose - true to print out status messages
    
    Throws:
    
    AreaFileException - on any error writing the file

Class AreaFile

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

AD_STATUS

AD_VERSION

AD_SENSORID

AD_IMGDATE

AD_IMGTIME

AD_STLINE

AD_STELEM

AD_NUMLINES

AD_NUMELEMS

AD_DATAWIDTH

AD_LINERES

AD_ELEMRES

AD_NUMBANDS

AD_PFXSIZE

AD_PROJNUM

AD_CRDATE

AD_CRTIME

AD_BANDMAP

AD_DATAOFFSET

AD_NAVOFFSET

AD_VALCODE

AD_STARTDATE

AD_STARTTIME

AD_STARTSCAN

AD_DOCLENGTH

AD_CALLENGTH

AD_LEVLENGTH

AD_SRCTYPE

AD_CALTYPE

AD_AVGSMPFLAG

AD_SRCTYPEORIG

AD_CALTYPEUNIT

AD_CALTYPESCALE

AD_AUXOFFSET

AD_CALOFFSET

AD_NUMCOMMENTS

AD_DIRSIZE

VERSION_NUMBER

Constructor Detail

AreaFile

AreaFile

AreaFile

Method Detail

isURLHandlerLoaded

isSubsetted

isRemote

getImageSource

getDir

getAreaDirectory

getNav

getNavigation

getCal

getAux

getData

getData

setCalType

getCalType

getFloatData

getData

getData

toString

main

close

save

save