Is a vector containing the dimension sizes of the subsetted region.

BYTESIZE is the size in bytes of the data in the subsetted region.

UPLEFT is a two-element vector containing the X and Y coordinates

of the upper-left corner of the subsetted region. LOWRIGHT is a

two-element vector containing the X and Y coordinates of the

lower-right corner of the subsetted region. STATUS is -1 and all

other outputs are [] if the operation fails.

GDextractregion

[DATA,STATUS] = HDFGD('extractregion',GRID_ID,...

REGION_ID,FIELDNAME)

Reads data from subsetted region of the specified field. STATUS is

-1 and DATA is [] if the operation fails.

NOTE: HDF files use C-style ordering for multidimensional array,

while MATLAB uses FORTRAN-style ordering. This means that the size

of the MATLAB array is flipped relative to the dimension sizes of

the subsetted region. For example, if the subsetted region has

dimensions 3-by-4-by-5, then DATA will have size 5-by-4-by-3. The

PERMUTE command is useful for making any necessary conversions.

GDdeftimeperiod

PERIOD_ID2 = HDFGD('deftimeperiod',GRID_ID,...

PERIOD_ID,STARTTIME,STOPID)

Defines a time period for a grid data set. PERIOD_ID can be the

output PERIOD_ID from a previous call or -1. STARTIME and STOPTIME

are scalars specifying the start and stop time of the period. The

output PERIOD_ID2 is -1 if the operation fails.

GDdefvrtregion

REGION_ID2 = HDFGD('defvrtregion',GRID_ID,...

REGION_ID,VERTOBJ,RANGE)

Subsets on a monotonic field or contiguous elements of a dimension.

REGION_ID is the region of period ID from a previous subset call,

or -1. VERTOBJ is a string containing the name of the dimension or

field to subset by. RANGE is a two-element vector containing the

minimum and maximum range for the subset. REGION_ID2 is -1 if the

operation fails.

GDgetpixels

[ROW,COL,STATUS] = HDFGD('getpixels',GRID_ID,...

LON,LAT)

Get pixel coordinates corresponding to latitude and longitude. LON

and LAT are vectors containing longitude and latitude coordinates

in degrees. ROW and COL are vectors containing the corresponding

zero-based row and column coordinates. STATUS is -1 and ROW and

COL are [] if the operation fails.

GDgetpixvalues

[DATA,BYTESIZE] = HDFGD('getpixvalues',GRID_ID, ...

ROW,COL,FIELDNAME)

Reads data from the specified field at the specified row and column

coordinates. ROW and COL are vectors containing zero-based row and

column coordinates. All entries along nongeographic dimensions

(that is, not XDim and YDim) are returned as a single column

vector. DATA is [] and BYTESIZE is -1 if the operation fails.

GDinterpolate

[DATA,BYTESIZE] = HDFGD('interpolate',GRID_ID,...

LON,LAT,FIELDNAME)

Performs bilinear interpolation on a field grid. LON and LAT are

vectors containing longitude and latitude coordinates. All grid

data entries along nongeographic dimensions (that is, not XDim and

YDim) are interpolated. The resulting values are returned as a

double-precision column vector. DATA is [] and BYTESIZE is -1 if

the operation fails.

GDdupregion

REGION_ID2 = HDFGD('dupregion',REGION_ID)

Duplicates a region. This routine copies the information stored in

a current region and generates a new identifier. It is useful when

the user wants to further set a region or period in multiple ways.

REGION_ID2 is -1 if the operation fails.

Tiling routines

---------------

GDdeftile

STATUS = HDFGD('deftile',GRID_ID,TILECODE,TILEDIMS)

Defines tiling dimensions for subsequent field definitions. The

number of tile dimensions and subsequent field dimensions must be

the same, and the tile dimensions must be integral divisors of the

corresponding field dimensions. TILECODE can be 'tile' or 'notile'.

TILEDIMS is a vector containing the tile dimensions.

GDtileinfo

[TILECODE,TILEDIMS,TILERANK,STATUS] = HDFGD( ...

'tileinfo',GRID_ID,FIELDNAME)

Retrieves tiling information about a field. STATUS is -1 and other

outputs are [] if the operation fails.

GDsettilecache

MAXCACHE_OUT = HDFGD('settilecache',GRID_ID,FIELDNAME,MAXCACHE)

Sets tile cache parameters. MAXCACHE is a scalar indicating the

maximum number of tiles to cache in memory. Upon success,

MAXCACHE_OUT is identical to MAXCACHE, but is -1 if the operation

fails.

GDreadtile

[DATA,STATUS] = HDFGD('readtile',GRID_ID, ...

FIELDNAME,TILECOORDS)

Reads from tile within the specified field. TILECOORDS is a vector

specifying the zero-based coordinates of the tile to be read. The

coordinates are specified in terms of tiles, not data elements.

STATUS is -1 and DATA is [] if the operation fails.

NOTE: HDF files use C-style ordering for multidimensional array,

while MATLAB uses FORTRAN-style ordering. This means that the size

of the MATLAB array is flipped relative to the dimension sizes of

the tile. For example, if the tile has dimensions 3-by-4, then

DATA has size 4-by-3. The PERMUTE command is useful for making any

necessary conversions.

GDwritetile

STATUS = HDFGD('writetile',GRID_ID,FIELDNAME, ...

TILECOORDS,DATA)

Writes to tile within a field. TILECOORDS is a vector specifying

the zero-based coordinates of the tile to be written to. The

coordinates are specified in terms of tiles, not data elements.

The class of DATA must match the HDF number type of the specified

field. A MATLAB string will be automatically converted to match

any of the HDF char types; other data types must match exactly.

NOTE: HDF files use C-style ordering for multidimensional array,

while MATLAB uses FORTRAN-style ordering. This means that the size

of the MATLAB array is flipped relative to the dimension sizes of

the tile. For example, if the tile has dimensions 3-by-4, then

DATA should have 4-by-3. The PERMUTE command is useful for making

any necessary conversions.

Please read the file hdf4copyright.txt for more information.

See also hdf, hdfsw, hdfpt.

<hdfpt> - MATLAB Gateway to HDF-EOS point interface.

HDFPT MATLAB interface to the HDF-EOS Point object.

HDFPT is the MATLAB interface to the HDF-EOS Point object. HDF-EOS is

an extension of NCSA (National Center for Supercomputing Applications)

HDF (Hierarchical Data Format). HDF-EOS is the scientific data format

standard selected by NASA as the baseline standard for EOS (Earth

Observing System).

HDFPT is a gateway to the Point functions in the HDF-EOS C library,

which is developed and maintained by EOSDIS (Earth Observing System

Data and Information System). A Point data set comprises a series of

data records taken at (possibly) irregular time intervals and at

scattered geographic locations. Each data record consists of a set of

one or more data values representing the state of a point in time

and/or space.

The general syntax for HDFPT is HDFPT(funcstr,param1,param2,...). There

is a one-to-one correspondence between PT functions in the HDF library

and valid values for funcstr. For example, HDFPT('detach',point_id)

corresponds to the C library call PTdetach(point_id).

Syntax conventions

------------------

There is a one-to-one mapping between Point functions in the HDF-EOS C

library and HDFPT syntaxes. For example, the C library contains this

function for getting the level name corresponding to given level index:

intn PTgetlevelname(int32 pointid, int32 level,

char *levelname, int32 *strbufsize)

The equivalent MATLAB usage is:

[LEVELNAME,STATUS] = HDFPT('getlevelname',POINTID,LEVEL)

LEVELNAME is a string. STATUS is either 0 (indicating success) or -1

(indicating failure).

Some of the C library functions accept input values that are defined in

terms of C macros. For example, the C PTopen() function requires an

access mode input that can be DFACC_READ, DFACC_RDWR, or DFACC_CREATE,

where these symbols are defined in the appropriate C header file.

Where macro definitions are used in the C library, the equivalent

MATLAB syntaxes use strings derived from the macro names. You can

either use a string containing the entire macro name, or you can use

omit the common prefix. You can use either upper or lower case. For

example, this C function call:

status = PTopen("PointFile.hdf",DFACC_CREATE)

is equivalent to these MATLAB function calls:

status = hdfpt('open','PointFile.hdf','DFACC_CREATE')

status = hdfpt('open','PointFile.hdf','dfacc_create')

status = hdfpt('open','PointFile.hdf','CREATE')

status = hdfpt('open','PointFile.hdf','create')

In cases where a C function returns a value with a macro definition,

the equivalent MATLAB function returns the value as a string containing

the lower-case short form of the macro.

HDF number types are specified by strings, including 'uchar8', 'uchar',

'char8', 'char', 'double', 'uint8', 'uint16', 'uint32', 'float',

'int8', 'int16', and 'int32'.

In cases where the HDF-EOS library accepts NULL, an empty matrix ([])

should be used.

Most routines return the flag STATUS, which is 0 when the routine

succeeds and -1 when the routine fails. Routines with syntaxes which

don't contain STATUS will return failure information in one of its

outputs as notated in the function syntaxes below.

Programming Model

-----------------

The programming model for accessing a point data set through HDFPT is

as follows:

1. Open the file and initialize the PT interface by obtaining a file

id from a file name.

2. Open or create a point data set by obtaining a point id from a

point name.

3. Perform desired operations on the data set.

4. Close the point data set by disposing of the point id.

5. Terminate point access to the file by disposing of the file id.

To access a single point data set that already exists in an HDF-EOS

file, use the following MATLAB commands:

fileid = hdfpt('open',filename,access);

pointid = hdfpt('attach',fileid,pointname);

% Optional operations on the data set...

status = hdfpt('detach',pointid);

status = hdfpt('close',fileid);

To access several files at the same time, obtain a separate file

identifier for each file to be opened. To access more than one point

data set, obtain a separate point id for each data set.

It is important to properly dispose of point id's and file id's so that

buffered operations are written completely to disk. If you quit MATLAB

or clear all MEX-files with PT identifiers still open, MATLAB will

issue a warning and automatically dispose of them.

Note that file identifiers returned by HDFPT are not interchangeable

with file identifiers returned by any other HDF-EOS or HDF function.

Function categories

-------------------

Point data set routines are classified into the following categories:

- Access routines initialize and terminate access to the PT

interface and point data sets (including opening and closing files).

- Definition routines allow the user to set key features of a point

data set.

- Basic I/O routines read and write data and metadata to a point data

set.

- Index I/O routines read and write information that links two tables

in a point data set.

- Inquiry routines return information about data contained in a point

data set.

- Subset routines allow reading of data from a specified geographic

region.

Access routines

---------------

PTopen

FILE_ID = HDFPT('open',FILENAME,ACCESS)

Given the filename and desired access mode, opens or creates an HDF

file in order to create, read, or write a point. ACCESS can be

'read', 'readwrite', or 'create'. FILE_ID is -1 if the operation

fails.

PTcreate

POINT_ID = HDFPT('create',FILE_ID,POINTNAME)

Creates a point data set with the specified name. POINTNAME is a

string contain the name of the point data set. POINT_ID is -1 if

the operation fails.

PTattach

POINT_ID = HDFPT('attach',FILE_ID,POINTNAME)

Attaches to an existing point data set within the file. POINT_ID is

-1 if the operation fails.

PTdetach

STATUS = HDFPT('detach',POINT_ID)

Detaches from point data set.

PTclose

STATUS = HDFPT('close', FILE_ID)

Closes file.

Definition routines

-------------------

PTdeflevel

STATUS = HDFPT('deflevel',POINT_ID,LEVELNAME,...

FIELDLIST,FIELDTYPES,FIELDORDERS)

Defines a new level within a point data set. LEVELNAME is the name

of the level to be defined. FIELDLIST is a string containing a

comma-separated list of field names in the new level. FIELDTYPES

is a cell array containing the number type string for each field.

Valid number type strings include 'uchar8', 'uchar', 'char8',

'char', 'double', 'uint8', 'uint16', 'uint32', 'float', 'int8',

'int16', and 'int32'. FIELDORDERS is a vector containing the order

for each field.

PTdeflinkage

STATUS = HDFPT('deflinkage',POINT_ID,PARENT,...

CHILD,LINKFIELD)

Defines a linkfield between two adjacent levels. PARENT is the

name of the parent level. CHILD is the name of the child level.

LINKFIELD is the name of a field that is defined at both levels.

Basic I/O routines

------------------

PTwritelevel

STATUS = HDFPT('writelevel',POINT_ID,LEVEL,DATA)

Appends new records to the specified level in a point data set.

LEVEL is the desired level index (zero-based). DATA must be a

P-by-1 cell array where P is the number of fields defined for the

specified level. Each cell of DATA must contain an M(k)-by-N matrix

of data where M(k) is the order of the k-th field (the number of

scalar values in the field) and N is the number of records. The

MATLAB class of the cells must match the HDF data type defined for

the corresponding fields. A MATLAB string will be automatically

converted to match any of the HDF char types; other data types must

match exactly.

PTreadlevel

[DATA,STATUS] = HDFPT('readlevel',POINT_ID,LEVEL,FIELDLIST,RECORDS)

Reads data from a given level in a point data set. LEVEL is the