home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Photo CD Demo 1
/
Demo.bin
/
hdf
/
vst_xtra.doc
< prev
Wrap
Text File
|
1980-02-06
|
11KB
|
369 lines
Vset 2.1beta doc Jason Ng 6/6/91 1
Jason Ng
15/May/91
HDF VSET 2.1beta
These are additional routines that are added to version 2.0. Refer to the
exsting HDF Vset manual for a description of the entire Vset interface.
Some terminology
FIELD
A field is defined by the user to describe data associated with one variable.
It consists of a name, type and order. Users of Vsets typically have datasets
of several variables, and hence define several fields. For example, a field
can be defined for a pressure variable to be called "pres". Its type is FLOAT,
and its order is 1.
ORDER
The number of distinct components in a field. Simple variables/fields like
pressure have order 1 (one distinct component, ie itself).
VGROUP
A Vset element where links to other elements are stored. A vgroup is used to
group related elements together. Elements can be vdatas, vgroups, and other
HDF elements like raster images, palettes, etc.
VDATA
A Vset element where data is stored. One vdata can store data of one or several
different fields. Fields can be of different types (integer, float, etc).
See FIELD.
VSET 2.1 VGROUP MANIPULATION ROUTINES
Vflocate()
Tests if a field exists in the vdatas belonging to a vgroup.
Fortran: VFLOCC
Vinqtagref()
Tests if a given tag/ref pair is in a vgroup.
Fortran: VFINGTR
Velts()
Returns the number of elements (links) in a vgroup.
Fortran: VFELTS
Vntagrefs()
Returns a count of the number of tag/ref pairs in a vgroup.
Fortran: VFNTR
Vgettagrefs()
Returns ALL the tag/ref pairs in a vgroup.
Not to be confused with Vgettagref() [VFGTR in Fortran].
Fortran: VFGTTRS
Vgettagref()
Returns a tag/ref pair at a specific position in the vgroup.
Not to be confused with Vgettagrefs() [VFGTRS in Fortran].
Fortran: VFGTTR
Vaddtagref()
Inserts a tag/ref pair into a vgroup.
Can be the tag/ref of non-vset elements.
Fortran: VFADTR
VSET 2.1 HIGH-LEVEL WRITE ROUTINES
VHstoredata()
Stores data of a simple field into a vdata.
Fortran: VHFSD
VHstoredatam()
Stores data of a compound field into a vdata.
Fortran: VHFSDM
VHmakegroup()
Creates a vgroup given some tag/ref pairs.
Fortran: VHFMKGP
Quick creation of simple Vsets in the majority of cases can be achieved using
only the High-Level Write routines.
VHstoredata - creates a vdata of a simple variable
VHstoredatam - creates a vdata of a compound variable
VHmakegroup - creates a vgroup.
VHstoredata() and VHstoredatam() are 2 routines used for storing data from
arrays into a vdata. VHmakegroup() creates a new vgroup given a series of
tag/ref pairs.
VHstoredata() is used for storing a simple variable. VHstoredatam() is used only
if a compound variable is to be stored as a single field of order > 1.
C EXAMPLE
Vset created by the C sample program:
/*
SAMPLE C PROGRAM
HDF VSET 2.1
Jason Ng NCSA MAY 1991
This program demonstrates the use of the high-level VSET write routines.
It shows how data can be stored in vdatas, and how vgroups can be created
from vdatas, vgroups and other HDF elements.
This example creates a file "vtesthi.hdf" that may be viewed using the
vset utility "vshow".
DETAILS
This example shows how pressure data and color data can be stored as a
vset. To store pressure data, a field named "PRES", is defined of
float type. The routine VHstoredata() stores the pressure values in a vdata.
Color data comprises 3 components (red, green, blue). These can be stored as
3 different fields in 3 vdatas. But this example shows that they can be
treated as ONE field, and stored together as a compound field called "COLOR".
The number of components of a field is called its order. In this case,
"COLOR" has order=3. (whereas "PRES" above has order=1).
The routine VHstoredatam() must be used to store values of a compound field.
This is similar to VHstoredata() but has an extra argument for the order
to be specified.
Finally a vgroup is created, and the ids of the created vdatas are stored
in the vgroup. This effectively groups the vdatas together. This example
also shows that you can insert another vgroup, as well as a non-vset element
(in this case, some element with tag=7777 and ref=1) into a vgroup.
*/
#include "vg.h"
#define fs "vtesthi.hdf"
#define NP 100
#define NC 60
#define ORDERC 3 /* 3 color components: rgb */
main (ac,av) int ac; char**av; {
printf("%s: tests high-level routines\n", av[0]);
printf("Creates 2 vdatas, a vgroup, and a non-vset element\n");
printf("then link them all into another vgroup\n");
printf("Vdata 1 contains an order-1 float field PRES\n");
printf("Vdata 2 contains an order-3 integer field COLOR\n\n");
printf("The non-vset element has tag=7777, ref=1\n");
doit();
printf("all done. created file %s\n", fs);
}
/* ------------------------------------------------------------------ */
doit() {
DF * f;
float pvals[NP];
int cvals[NC][ORDERC];
int i,j;
int16 pid, cid; /* refs of vdatas */
int16 eid; /* empty vgroup's ref */
int16 gid; /* vgroup's ref */
int16 tags[10], refs[16];
char *CLS = "EXAMPLE";
/* --- generate data here --- */
for(i=0;i<NP;i++) pvals[i] = 100.0 + i * 0.001;
for(i=0;i<NC;i++) for(j=0;j<3;j++) cvals[i][j] = i + j*100;
/* ---- open a new file --- */
if (NULL==(f=DFopen(fs,DFACC_ALL,0))) { printf("open %s err\n",fs); exit(0); }
/* ---- create 2 vdatas --- */
pid = VHstoredata (f, "PRES", pvals ,NP, LOCAL_FLOATTYPE, "pressure vals",CLS);
if (pid == -1) { printf(" VHstoredata store PRES err. "); }
cid = VHstoredatam(f, "COLOR", cvals, NC, LOCAL_INTTYPE, "rgb colors", CLS, 3);
if (cid == -1) { printf(" VHstoredata store COLOR err. "); }
eid = VHmakegroup (f, tags, refs, 0, "This is an EMPTY vgroup", CLS);
if (eid == -1) { printf(" VHmakegroup err\n"); }
/* --- create a new vgroup to store the 2 vdatas and the empty vgroup -- */
tags[0] = VSDESCTAG; refs[0] = pid;
tags[1] = VSDESCTAG; refs[1] = cid;
tags[2] = VGDESCTAG; refs[2] = eid;
tags[3] = 7777 ; refs[3] = 1;
gid = VHmakegroup (f, tags, refs, 4, "here is a vset with 4 links", CLS);
if (eid == -1) { printf(" VHmakegroup err\n"); }
/* --- close the file --- */
DFclose (f);
}
FORTRAN EXAMPLE
Vset created by the Fortran sample program.
c ==================================================================
c FORTRAN EXAMPLE
c
c HDF VSET 2.1
c Jason Ng NCSA MAY 1991
c
c This program creates a Vset to store an array of pressure values,
c and an array of color-triplets (red-green-blue). It demonstrate
c the use of the Vset high-level write routines.
c The pressure data is stored in one vdata (pid), and the color-triplets
c are stored in another vdata (cid). These ids are then stored together
c in a vgroup, thereby logically grouping them as one vset.
c
c Note that pressure is a simple variable. It is stored using the
c function VHFSD. But color-triplet data is a compound variable, with
c 3 components (red,green,blue). The function VHFSDM is used instead
c so that the order (the number of components, ie 3) can be specified.
c
c The HDF file that is created,"eh.hdf", can be looked at with the
c Vset utility "vshow"
c ==================================================================
program SAMPLE
real pbuf(100)
integer cbuf(3,60)
integer i,j, npres, ncolor
integer f
integer pid, cid, vgid
character*10 class
integer tagnums(10), refnums(10), ntagref
c --- routines and functions used
external DFOPEN, DFCLOSE
integer DFOPEN
external VHFSD, VHFSDM, VHFMKGP
integer VHFSD, VHFSDM, VHFMKGP
c --- The parameters below are defined constants from "vg.h"
c -- float and integer types
integer T_INT, T_FLOAT
parameter (T_INT=2)
parameter (T_FLOAT=3)
c --- HDF tag for vgroup and vdata.
integer VDATTAG, VGPTAG
parameter (VGPTAG=1965)
parameter (VDATTAG=1962)
c --- full file access
integer FULLACC
parameter (FULLACC=7)
c ------ generate pressure data -------------------
npres = 100
do 111 i=1,npres
pbuf(i) = 0.01 * i + 500
111 continue
c ------ generate color-triplet (rgb) data -------
ncolor = 60
do 222 i=1,ncolor
do 225 j=1,3
cbuf(j,i) = i + j * 100
225 continue
222 continue
class = 'example'
c --- open the HDF file
f = DFOPEN ('eh.hdf', FULLACC, 0)
c --- store pressure values in a new vdata
pid = VHFSD (f, 'PRES', pbuf, npres, T_FLOAT,
1 'pressure values', class)
print *, 'Pressure vdata id is ', pid
c --- store color-triplet values in a new vdata
c Note the argument 3 (for order=3 for a triplet)
cid = VHFSDM (f, 'RGB', cbuf, ncolor, T_INT,
1 'a set of rgb values', class, 3)
print *, 'Color-triplet vdata id is ', cid
c --- create a new vgroup and then group the 2 vdatas into it
tagnums(1) = VDATTAG
tagnums(2) = VDATTAG
refnums(1) = pid
refnums(2) = cid
ntagref = 2
vgid = VHFMKGP (f,tagnums ,refnums, ntagref,
1 'vgroup with 2 vdatas',
1 class)
print *, 'Vgroup id is ', vgid
c --- close the HDF file
call DFCLOSE (f)
print *,'HDF VSet file eh.hdf created'
end
Calling Sequences
int VHstoredata (f, field, buf, n, datatype, vsname, vsclass)
DF * f;
char * field;
unsigned char buf[];
int32 n;
char * vsname, * vsclass;
int datatype;
Creates a new vdata and store data for one simple field. You give it the name
and class (strings)of that vdata, and the field name (eg "PRES" for pressure),
and tell it what datatype the data will be in. The data is passed in as the
array buf[], and you tell it how many values there are (n).
Datatype is one of LOCAL_INTTYPE, LOCAL_LONGTYPE,LOCAL_FLOATTYPE,
LOCAL_CHARTYPE.
To store acompound field, use VHstoredatam() instead.
int VHstoredatam (f, field, buf, n, datatype, vsname, vsclass, order)
DF *f;
char *field;
float buf[];
int32 n;
int datatype;
int order;
char *vsname, *vsclass;
Creates a new vdata and store data for one compound field. You give it the
name and class (strings)of that vdata, and the field name (eg "PLIST3" for
pressure), and tell it what datatype the data will be in. In addition, you
need to tell it the order of that field. (ie, how many components there are
per data item). The data is passed in as the array buf[], and you tell it
how many values there are (n).
Datatype is one of LOCAL_INTTYPE, LOCAL_LONGTYPE,LOCAL_FLOATTYPE,
LOCAL_CHARTYPE.
This routine also works for a simple field - set the order to 1. Or you can use
VHstoredata() instead.
int VHmakegroup (f, tagarray, refarray , n, vgname, vgclass)
int tagarray[], refarray[];
int n;
char *vgname, *vgclass;
Creates a new vgroup. You give it the name, class and an array of tags and refs.
You also tell it how many tag/ref pairs there are. It will create the vgroup,
and return the ref number (id) of that new vgroup. Vgname and vgclass are any
text string to name the vgroup.