edu.wisc.ssec.mcidas
Class AreaFile

java.lang.Object
  edu.wisc.ssec.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.

Author:

Tom Whittaker, SSEC, Tommy Jasmin, SSEC

See Also:

Serialized Form

Field Summary

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

AreaFile(String source)
Creates an AreaFile object that allows reading of McIDAS 'area' file format image data.

AreaFile(String filename, Applet parent)
creates an AreaFile object that allows reading of McIDAS 'area' file format image data from an applet

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

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(String filename,
                Applet parent)
         throws AreaFileException

creates an AreaFile object that allows reading of McIDAS 'area' file format image data from an applet

Parameters:

filename - the disk filename (incl path) to read from

parent - the parent applet

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 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