Macros
#define	GS_READ 0

#define	GS_WRITE 1

#define	GS_IFILE_SUCCESS 1

#define	GS_IFILE_FAILURE 2

#define	GS_OBJECT_TYPE_UNKNOWN 0

#define	GS_OBJECT_TYPE_METADATA_GROUP 1

#define	GS_OBJECT_TYPE_IMAGE 2

#define	GS_OBJECT_TYPE_VECTOR 3

#define	GS_OBJECT_TYPE_VECTOR2D 4

#define	GS_OBJECT_TYPE_VECTOR3D 5

#define	GS_OBJECT_TYPE_TIN 6

#define	GS_OBJECT_TYPE_MESH2D 7

#define	GS_OBJECT_TYPE_MESH3D 8

#define	GS_OBJECT_TYPE_RASTER 9

#define	GS_OBJECT_TYPE_IFILE 10

#define	GS_OBJECT_TYPE_FILE 11

#define	GS_OBJECT_TYPE_METADATA_DATASET 12

#define	GS_OBJECT_TYPE_METADATA_IFILE 13

#define	GS_OBJECT_TYPE_UNDER_CONSTRUCTION -1

#define	GS_COORDINATES_UNKNOWN 0

#define	GS_COORDINATES_DEGREES 1

#define	GS_COORDINATES_METERS 2

#define	GS_COORDINATES_PIXELS 3

Typedefs
typedef char complex	ci16_t

typedef short int complex	ci32_t

typedef int complex	ci64_t

typedef float complex	c64_t

typedef double complex	c128_t

Functions
bstring	GS_H5ObjectTypeAsString (int objtype)
	GS_H5ObjectTypeAsString returns a printable version of HDF5 object type. More...

bstring	GS_GSObjectTypeAsString (int objtype)
	GS_GSObjectTypeAsString returns printable version of the object type. More...

int	GS_CheckFileExistence (const_bstring filename)
	GS_CheckFileExistence checks for the existence of a specified file. More...

void	GS_init ()
	GS_init initialize some global strings. More...

int	GS_ValidID (hid_t id)
	GS_ValidID returns whether the given object-id is a valid identifier. More...

bstring	GS_GetIDName (hid_t id)
	GetIDName returns the name of the given handle. More...

int	GS_GetStringAttribute (hid_t object_id, const_bstring name, bstring value)
	GS_GetStringAttribute reads a string attribute from an object and returns its value. More...

int	GS_SetStringAttribute (hid_t object_id, const_bstring name, const_bstring value)
	GS_SetStringAttribute sets the value of a string attribute for a given object. More...

int	GS_ObjectIsFile (hid_t id)
	GS_ObjectIsFile determines if an object-id refers to a file. More...

int	GS_ObjectIsDataset (hid_t id, const_bstring name)
	GS_ObjectIsDataset determines if an object is a dataset. More...

int	GS_ObjectIsDatasetByID (hid_t id)
	GS_ObjectIsDatasetByID determines if an object-id refers to a dataset. More...

int	GS_ObjectIsGroup (hid_t id, const_bstring name)
	GS_ObjectIsGroup determines if a named object is a group. More...

int	GS_ObjectIsGroupByID (hid_t id)
	GS_ObjectIsGroupByID determines if an object-id refers to a group. More...

int	GS_CheckInternalName (hid_t object_id, const_bstring thename)
	GS_CheckInternalName checks for existence of an object name in the file. More...

hid_t	GS_CreateAccessPlist (void)
	GS_CreateAccessPlist creates an HDF5 access parameter list. More...

hid_t	GS_FileCreate (const_bstring filename)
	GS_FileCreate creates an empty GeoSci datafile. More...

int	GS_FileDelete (const_bstring filename)
	GS_FileDelete deletes an existing GeoSci datafile. More...

hid_t	GS_FileOpen (const_bstring dbname, const_bstring access)
	GS_FileOpen opens a GeoSci datafile. More...

int	GS_FileFlush (hid_t object_id)
	GS_FileFlush forces the datafile to be updated. More...

int	GS_FileClose (hid_t file_id)
	GS_FileClose closes a GeoSci datafile. More...

int	GS_FileCloseAllObjects (hid_t file_id)
	GS_FileCloseAllObjects closes all open objects in a file. More...

int	GS_FileIsWriteable (hid_t id)
	GS_FileIsWriteable returns if file is writeable or not. More...

int	GS_FileCopy (bstring oldname, bstring newname)
	GS_FileCopy copies a GeoSci datafile to a new file. More...

int	GS_FileIsOpen (const_bstring filename)
	GS_FileIsOpen determines if a GeoSci datafile is already open in the current process. More...

int	GS_FileRename (const_bstring oldname, const_bstring newname)
	GS_FileRename renames an existing GeoSci datafile. More...

int	GS_FileReport (const_bstring filename, bstring report_string)
	GS_FileReport summarizes the contents of a GeoSci datafile. More...

hid_t	GS_GetValidFileID (hid_t id)
	GS_GetValidFileID returns a valid FileID that contains the object. More...

bstring	GS_GetFilename (hid_t id)
	GetFilename returns the filename associated with an ID. More...

herr_t	GS_SetCacheSize (hid_t file_id, size_t cache_size)
	GS_SetCacheSize sets the metadata cache size for a GeoSci datafile. More...

int	GS_FileCommitDatatypes (hid_t file_id)
	GS_FileCommitDatatypes commits the complex raster datatypes to a file. More...

char *	GS_Dirname (const char *name)
	Dirname returns the directory name for a UNIX pathname. More...

hid_t	GS_DatasetCreate (hid_t source, const_bstring name, int datatype, int ndims, int *size, int is_extendable, int is_compressed)
	GS_DatasetCreate creates a dataset in a GeoSci datafile. More...

int	GS_DatasetDelete (hid_t file_id, const_bstring dataset_name)
	GS_DatasetDelete deletes a a dataset in a GeoSci datafile. More...

hid_t	GS_DatasetOpen (hid_t source, const_bstring name)
	GS_DatasetOpen opens a dataset in a GeoSci datafile. More...

hid_t	GS_DatasetClose (hid_t id)
	GS_DatasetClose closes a dataset in a GeoSci datafile. More...

int	GS_DatasetRename (hid_t group_id, const_bstring oldname, const_bstring newname)
	GS_DatasetRename renames a dataset in a GeoSci datafile. More...

hid_t	GS_DatasetGetParent (hid_t id)
	GS_DatasetGetParent returns the parent object-id for a Dataset. More...

int	GS_DatasetGetDatatype (hid_t id, const_bstring name)
	GS_DatasetGetDatatype returns the GeoSci datatype for data in the Dataset. More...

int	GS_DatasetGetDatatypeByID (hid_t id)
	GS_DatasetGetDatatypeByID returns the GeoSci datatype for the data in the Dataset. More...

int	GS_DatasetGetDimensionsByID (hid_t id, long int **size)
	GS_DatasetGetDimensionsByID returns the current dimensions for the Dataset. More...

int	GS_DatasetGetDimensions (hid_t id, const_bstring name, long int **size)
	GS_DatasetGetDimensions returns the current dimensions for the Dataset. More...

hid_t	GS_DatasetCopy (hid_t source, hid_t destination_group_id, const_bstring destination_dataset_name)
	GS_DatasetCopy copies a dataset to an existing Group: this can be in the same group, a different group, or a different file. More...

int	GS_DatasetRead (hid_t dataset_id, const long int offsets, const long int sizes, int datatype, void *buffer)
	GS_DatasetRead reads data from a dataset. More...

int	GS_DatasetWrite (hid_t dataset_id, const long int offsets, const long int sizes, int datatype, const void *buffer)
	GS_DatasetWrite writes data to a dataset. More...

int	GS_DataConversion (int in_type, const void in_buffer, int out_type, void out_buffer, int nelements)
	GS_DataConversion converts a data buffer between different types. More...

int	GS_RasterTypeNumbytes (int datatype)

int	GS_ConvertFromHDFDatatype (hid_t datatype)
	GS_ConvertFromHDFDatatype returns the GeoSci datatype for the given HDF datatype. More...

hid_t	GS_ConvertToHDFDatatype (int datatype)
	GS_ConvertToHDFDatatype returns the HDF datatype for the given GeoSci datatype. More...

int	GS_HDFDatatypeClose (hid_t id)
	GS_HDFDatatypeClose closes an HDF datatype. More...

bstring	GS_PathnameNodir (const_bstring name)
	GS_PathnameNoDir strips the directory name from the pathname. More...

bstring	GS_PathnameGetDir (const_bstring name)
	GS_PathnameGetDir returns the directory name of the pathname. More...

bstring	GS_PathnameGetHDFDir (const_bstring name)
	GS_PathnameGetHDFDir returns the directory name of the pathname. More...

bstring	GS_PathnameJoin (const_bstring front, const_bstring back)
	GS_PathnameJoin joins 2 pieces of a pathname. More...

hid_t	GS_GroupCreate (hid_t file_id, const_bstring groupname)
	GS_GroupCreate creates a new group in a GeoSci Datafile. More...

hid_t	GS_GroupOpen (hid_t source, const_bstring name)
	GS_GroupOpen opens an existing group in a GeoSci datafile. More...

int	GS_GroupClose (hid_t id)
	GS_GroupClose closes a group in a GeoSci Datafile. More...

int	GS_GroupCloseAllObjects (hid_t id)
	GS_GroupCloseAllObjects closes all open objects in a group. More...

hid_t	GS_GroupCopy (hid_t source, hid_t destination_object_id, const_bstring destination_group_name)
	GS_GroupCopy copies a group to another location. More...

int	GS_GroupRename (hid_t id, const_bstring oldname, const_bstring newname)
	GS_GroupRename renames a group in a GeoSci datafile. More...

int	GS_GroupDelete (hid_t file_id, const_bstring group_name)
	GS_GroupDelete deletes a group in a GeoSci datafile. More...

int	GS_AppendMetadata (hid_t object_id, const_bstring metadata_name, const_bstring value)
	GS_AppendMetadata appends the given string to the metadata item. More...

int	GS_FileCreateMetadata (hid_t file_id, const_bstring descriptor)
	GS_FileCreateMetadata Creates metadata in a GeoSci datafile. More...

int	GS_ImageCreateMetadata (hid_t file_id, const_bstring image_name, const_bstring descriptor)
	GS_ImageCreateMetadata fills the standard image metadata attributes with the values that are passed in. More...

int	GS_VectorCreateMetadata (hid_t file_id, const_bstring vector_name, const_bstring descriptor)
	GS_VectorCreateMetadata creates vector metadata. More...

int	GS_RasterCreateMetadata (hid_t image_id, const_bstring raster_name, int raster_type, int npixels, int nlines, const_bstring descriptor)
	GS_RasterCreateMetadata fills the standard raster metadata attributes with the values that are passed in. More...

int	GS_ObjectIsIFileByID (hid_t dataset_id)
	GS_ObjectIsIFileByID determines if the objectID is an internal file. More...

int	GS_ObjectIsIFile (hid_t id, const_bstring name)
	GS_ObjectIsIFile determines if the object is an internal file. More...

int	GS_ObjectIsImageByID (hid_t id)
	GS_ObjectIsImageByID determines if the object is an image. More...

int	GS_ObjectIsImage (hid_t file_id, const_bstring image_name)
	GS_ObjectIsImage determines if the object is an image. More...

int	GS_ObjectIsMetadataDatasetByID (hid_t dataset_id)
	ObjectIsMetadataDatasetByID determines if the objectid is a metadata dataset. More...

int	GS_ObjectIsMetadataDataset (hid_t id, const_bstring name)
	ObjectIsMetadataDataset determines if the object is a metadata dataset. More...

int	GS_ObjectIsMetadataIFileByID (hid_t dataset_id)
	GS_ObjectIsMetadataIFileByID determines if the object-id refers to a metadata internal-file. More...

int	GS_ObjectIsMetadataIFile (hid_t id, const_bstring name)
	GS_ObjectIsMetadataIFile determines if the object refers to a metadata internal-file. More...

int	GS_ObjectIsRasterByID (hid_t dataset_id)
	GS_ObjectIsRasterByID determines if the object-id refers to a raster image. More...

int	GS_ObjectIsRaster (hid_t id, const_bstring name)
	GS_ObjectIsRaster determines if the object is a raster image. More...

int	GS_ObjectIsVectorByID (hid_t id)
	GS_ObjectIsVectorByID determines if the object-id refers to a vector. More...

int	GS_ObjectIsVector (hid_t id, const_bstring name)
	GS_ObjectIsVector determines if the object is a vector. More...

int	GS_ObjectLock (hid_t id)
	GS_ObjectLock makes an object read-only. More...

int	GS_ObjectUnlock (hid_t id)
	GS_ObjectUnlock changes and object to have read-write status. More...

int	GS_SplitHistory (const_bstring history_string, bstring front, bstring back)
	GS_SplitHistory splits history string into front and back. More...

int	GS_UpdateMetadata (hid_t object_id, const_bstring name, bstring value)
	GS_UpdateMetadata update a metadata item for the given object. More...

int	GS_ValidMetadataName (int object_type, const_bstring name)
	GS_ValidMetadataName check if the name is a valid metadata item for the given object type. More...

int	GS_DatatypeIsComplex (int datatype)
	GS_DatatypeIsComplex returns TRUE if a complex datatype. More...

bstring	GS_DatatypeAsString (int datatype)
	GS_DatatypeAsString return a string representing the datatype. More...

bstring	GS_DatasetReport (hid_t dataset_id)
	GS_DatasetReport returns a brief description of the dataset. More...

int	GS_DatasetIsWriteable (hid_t file_id, const_bstring dataset_name)
	GS_DatasetIsWriteable returns if dataset is writeable or not. More...

int	GS_DatasetIsWriteableByID (hid_t dataset_id)
	GS_DatasetIsWriteableByID returns if dataset is writeable or not. More...

int	GS_GroupIsWriteable (hid_t file_id, const_bstring group_name)
	GS_GroupIsWriteable returns if the group is writeable or not. More...

int	GS_GroupIsWriteableByID (hid_t group_id)
	GS_GroupIsWriteableByID returns if the group is writeable or not. More...

bstring	GS_GroupReport (hid_t group_id)
	GS_GroupReport returns a one-line brief description of the group. More...

int	GS_GroupGetType (hid_t group_id)
	GS_GroupGetType returns the type of a group in a GeoSci datafile. More...

int	GS_GroupSetType (hid_t group_id, int typecode)
	GS_GroupSetType sets the type of a group in a GeoSci datafile. More...

bstring	GS_GroupGetDatum (hid_t group_id)
	GS_GroupGetDatum returns a description of the relevant datum if one exists. More...

bstring	GS_GroupGetProjection (hid_t group_id)
	GS_GroupGetProjection returns a description of the relevant projection. More...

int	GS_GroupGetBounds (hid_t group_id, double xmin, double xmax, double ymin, double ymax)
	GS_GroupGetBounds returns the rectangular bounding coordinates. More...

bstring	GS_DatasetGetDatum (hid_t dataset_id)
	GS_DatasetGetDatum returns a description of the relevant datum if one exists. More...

bstring	GS_DatasetGetProjection (hid_t dataset_id)
	GS_DatasetGetProjection returns a description of the relevant projection. More...

int	GS_DatasetGetBounds (hid_t dataset_id, double xmin, double xmax, double ymin, double ymax)
	GS_DatasetGetBounds returns the rectangular bounding coordinates. More...

int	GS_ObjectGetH5Children (hid_t object_id, int nobjs, bstring objnames, int *objtypes)
	GS_ObjectGetH5Children returns list of all children objects. More...

int	GS_ObjectGetGSChildren (hid_t object_id, int nobjs, bstring objnames, int *objtypes)
	GS_ObjectGetGSChildren returns list of GeoSci children objects. More...

int	GS_DatasetGetType (hid_t dataset_id)
	GS_DatasetGetType returns the type of a GeoSci Dataset. More...

int	GS_DatasetSetType (hid_t dataset_id, int typecode)
	GS_DatasetSetType set the type of a dataset in a GeoSci file. More...

hid_t	GS_ImageCreate (hid_t file_id, const_bstring image_name, const_bstring image_descriptor)
	GS_ImageCreate creates a new image in a GeoSci file and opens it. More...

int	GS_ImageClose (hid_t image_id)
	GS_ImageClose closes an Open Image}. More...

hid_t	GS_ImageOpen (hid_t file_id, const_bstring image_name)
	GS_ImageOpen opens an existing image. More...

int	GS_ImageDelete (hid_t file_id, const_bstring image_name)
	GS_ImageDelete deletes an existing image. More...

int	GS_AppendHistory (hid_t object_id, const_bstring history_line)
	GS_AppendHistory appends to the history metadata. More...

int	GS_AbortedHistory (hid_t object_id, const_bstring history_line)
	GS_AbortedHistory writes aborted message to history metadata. More...

hid_t	GS_RasterCreate (hid_t image_id, const_bstring raster_name, int raster_type, int npixels, int nlines, const_bstring descriptor)
	GS_RasterCreate create new image raster for a GeoSci Image. More...

hid_t	GS_RasterOpen (hid_t image_id, const_bstring raster_name)
	GS_RasterOpen opens existing raster dataset. More...

int	GS_RasterClose (hid_t raster_id)
	GS_RasterClose closes an open raster dataset. More...

int	GS_RasterDelete (hid_t image_id, const_bstring raster_name)
	GS_RasterDelete deletes an existing raster. More...

bstring	GS_GetRasterTypeAsString (int datatype)
	GS_GetRasterTypeAsString returns a string representing the datatype. More...

int	GS_RasterPixelSize (hid_t raster_id, int func, double x_pixelsize, double y_pixelsize, bstring pixel_units)
	GS_RasterPixelSize reads/writes Raster Pixel Size. More...

int	GS_RasterSizeInfo (hid_t raster_id, int npixels, int nlines)
	GS_RasterSizeInfo returns the number of pixels and lines in a raster. More...

int	GS_RasterCheckWindow (hid_t file_id, const_bstring image_name, int *window)
	GS_RasterCheckWindow checks whether a requested window selection is within the bounds of an image. It will also default a window specification to be the whole image if XSize and/or YSize are zero. More...

int	GS_RasterCheckWindowByID (hid_t image_id, int *window)
	GS_RasterCheckWindowByID checks whether a requested window selection is within the bounds of a raster. It will also default a window specification to be the whole raster if XSize and/or YSize are zero. More...

int	GS_CheckWindowInside (int window_in, const int window_enclosing)
	CheckWindowInside checks if one Window is contained by another. More...

int	GS_RasterTypeIsInteger (int datatype)
	GS_RasterTypeIsInteger returns TRUE for integer types. More...

int	GS_RasterTypeIsComplex (int datatype)
	GS_RasterTypeIsComplex returns TRUE for complex types. More...

int	GS_CheckUniqueName (hid_t file_id, const char *thename)
	GS_CheckUniqueName check if name is unique. More...

Function Documentation

int GS_AbortedHistory	(	hid_t	object_id,
		const_bstring	history_line
	)

GS_AbortedHistory writes aborted message to history metadata.

AbortedHistory() writes an "Aborted" message to the history metadata, and updates the last_update_datetime metadata item. This works for any object with a "history" metadata item, and a "last_update_datetime" metadata item.

See also: GS_AppendHistory(), GS_SplitHistory()

Parameters

[in]	object_id	ID of a file, an image, or any other valid object in a GeoSci file.
[in]	history_line	This string is appended to the history metadata item for the given object, along with " *ABORTED* "

Returns: TRUE on success, FALSE otherwise.

Example: Before writing to an image, write an aborted message in case of a run-time failure. After successfully modifying the image, write a new history, which over-writes the aborted message.
1 hid_t image_id;

2 bstring name = bfromcstr("/Image3");

3 image_id=GS_ImageOpen(file_id,name);

4 bdestroy(name);

5

6 bstring tname = bfromcstr("Task_name");

7 GS_AbortedHistory(image_id,tname);

8 bdestroy(tname);

9

10 ... modify the image ....

11

12 bstring tname2 = bfromcstr("Task_name(task_param1,task_param2,...)");

13 GS_AppendHistory(image_id,tname2);

14 bassigncstr(tname2,"Task_name: param1");

15 GS_AppendHistory(file_id,tname2);

16 bdestroy(tname2);

int GS_AppendHistory	(	hid_t	object_id,
		const_bstring	history_line
	)

GS_AppendHistory appends to the history metadata.

AppendHistory() appends the given string to the history metadata item, and updates the last_update_datetime metadata item. This works for any object with a "history" metadata item, and a "last_update_datetime" metadata item.

See also: GS_AppendMetadata()

Parameters

[in]	object_id	ID of a file, an image, or any other valid object in a GeoSci file.

int GS_AppendMetadata	(	hid_t	object_id,
		const_bstring	metadata_name,
		const_bstring	value
	)

GS_AppendMetadata appends the given string to the metadata item.

See also: GS_UpdateMetadata()

Parameters

[in]	object_id	ID of a file, and image, or any other valid object in a GeoSci file.
[in]	metadata_name	The name of the metadata item to update.
[in]	value	This string is appended to the metadata item for the given object.

Returns: TRUE on success, FALSE on failure.

Example:: After writing to an image, update it's history.
1 hid_t image_id;

2 bstring name = bfromcstr("Image3");

3 image_id=GS_ImageOpen(file_id,name);

4 bdestroy(name);

5 ... modify the image ....

6 bstring history=bfromcstr("hsitory");

7 bstring history_value = bfromcstr("Task_name(task_param1,task_param2)");

8 GS_AppendMetadata(image_id,history,history_value);

9 bdestroy(history);

10 bdestroy(history_value);

Details:: A special case is when writing a "history" metadata item. In this case, if the last line of the history contains "ABORTED", we remove this last line, and append the new line. In essence this ends up "over-writing" the "ABORTED" line. The reason for this is to have an aborted message when there is a failure, but no aborted message on success.

int GS_CheckFileExistence ( const_bstring filename )

GS_CheckFileExistence checks for the existence of a specified file.

Parameters

[in] filename Name of file to check for.

Returns: Returns TRUE if the file exists, or FALSE if it does not exist (or is not accessable).

Example: 1 bstring name = bfromcstr("a.dat");

2 if(GS_CheckFileExistence(name)){

3 printf("a.data exists\n");

4 } else {

5 printf("a.data does not exist\n");

6 }

7 bdestroy(name);

int GS_CheckInternalName	(	hid_t	object_id,
		const_bstring	thename
	)

GS_CheckInternalName checks for existence of an object name in the file.

See also: GS_RasterCheckWindow()

Parameters

[in]	object_id	Handle of an already-open GeoSci object.
[in]	name	Name of the object one wishes to test. Must be a relative pathname, relative to the object in "object_id". If object_id is a file, then this can be an absolute name. For example: /groupa/group1/datasetw.

Returns: TRUE if the name exists, FALSE if not.

Example:: Test if the name "Channel_3" already exists or not:
1 hid_t file_id;

2 bstring name = bfromcstr("Channel_3");

3 if(GS_CheckInternalName(file_id,name) ){

4 printf("Name: \"Channel_3\" is already in use.\n");

5 }// endif

6 bdestroy(name);

int GS_CheckUniqueName	(	hid_t	object_id,
		const char *	thename
	)

GS_CheckUniqueName check if name is unique.

Parameters

[in]

int GS_CheckWindowInside	(	int *	window_in,
		const int *	window_enclosing
	)

CheckWindowInside checks if one Window is contained by another.

See also: GS_RasterCheckWindow()

Parameters

[in]	window	Vector containing desired window specification. window[0] = Xoffset window[1] = Yoffset window[2] = Xsize window[3] = Ysize If window[2] is 0, window[2] will be set to image X size - window[0]. If window[3] is 0, window[3] will be set to image Y size - window[1].
[in]	window_enclosing	Vector containing enclosing window specification.

Returns: TRUE is returned is window is enclosed by window_enclosing, False otherwise. Note that "enclosing" includes the case where any border are the same.

Example: In this example a user specified window is checked for validity within some other window.
1 ...

2 int dbiw[4];

3 int dbiw_enclosing[4];

4 ...

5 // Determine user requested window.

6 ...

7 if( GS_CheckWindowInside( dbiw, dbiw_enclosing )) {

8 printf("The window is enclosed.\n");

9 }

10 ...

int GS_ConvertFromHDFDatatype ( hid_t datatype )

GS_ConvertFromHDFDatatype returns the GeoSci datatype for the given HDF datatype.

See also: GS_ConvertToHDFDatatype

Parameters

[in] datatype A handle to an HDF5 datatype.

Returns: The GeoSci typecode is returned, and is 0 if invalid. Valid datatypes are:
GS_DATATYPE_UI1 (Unsigned Integer, 1-bit)
GS_DATATYPE_UI8 (Unsigned Integer, 8-bit)
GS_DATATYPE_SI8 (Signed Integer, 8-bit)
GS_DATATYPE_CI8 (Complex Integer, 8-bit (not supported))
GS_DATATYPE_UI16 (Unsigned Integer, 16-bit)
GS_DATATYPE_SI16 (Signed Integer, 16-bit)
GS_DATATYPE_CI16 (Complex Integer, 16-bit)
GS_DATATYPE_UI32 (Unsigned Integer, 32-bit)
GS_DATATYPE_SI32 (Signed Integer, 32-bit)
GS_DATATYPE_CI32 (Complex Integer, 32-bit)
GS_DATATYPE_CI64 (Complex Integer, 64-bit)
GS_DATATYPE_R32 (Real, 32-bit)
GS_DATATYPE_R64 (Real, 64-bit)
GS_DATATYPE_C64 (Complex, 64-bit)
GS_DATATYPE_C128 (Complex, 128-bit)
GS_DATATYPE_UI64 (Unsigned Integer, 64-bit)
GS_DATATYPE_SI64 (Signed Integer, 64-bit)

Example: Get the GeoSci equivalent of the HDF5 type H5T_NATIVE_INT8:
1 int gs_type;

2 gs_type = GS_ConvertFromHDFDatatype(H5T_NATIVE_INT8);

3 if(!gs_type) {

4 printf("GS_ConvertFromHDFDatatype failure\n");

5 }

Details: Currently this checks against the HDF5 "NATIVE" datatypes. I suspect this will not work if the data is in a different byte order. Need to fix this. (LEP: Aug 9, 2014).

hid_t GS_ConvertToHDFDatatype ( int datatype )

GS_ConvertToHDFDatatype returns the HDF datatype for the given GeoSci datatype.

See also: GS_ConvertFromHDFDatatype

Parameters

[in] datatype An integer representing a GeoSci datatype. Valid datatypes are:
GS_DATATYPE_UI1 (Unsigned Integer, 1-bit)
GS_DATATYPE_UI8 (Unsigned Integer, 8-bit)
GS_DATATYPE_SI8 (Signed Integer, 8-bit)
GS_DATATYPE_CI8 (Complex Integer, 8-bit (not supported))
GS_DATATYPE_UI16 (Unsigned Integer, 16-bit)
GS_DATATYPE_SI16 (Signed Integer, 16-bit)
GS_DATATYPE_CI16 (Complex Integer, 16-bit)
GS_DATATYPE_UI32 (Unsigned Integer, 32-bit)
GS_DATATYPE_SI32 (Signed Integer, 32-bit)
GS_DATATYPE_CI32 (Complex Integer, 32-bit)
GS_DATATYPE_CI64 (Complex Integer, 64-bit)
GS_DATATYPE_R32 (Real, 32-bit)
GS_DATATYPE_R64 (Real, 64-bit)
GS_DATATYPE_C64 (Complex, 64-bit)
GS_DATATYPE_C128 (Complex, 128-bit)
GS_DATATYPE_UI64 (Unsigned Integer, 64-bit)
GS_DATATYPE_SI64 (Signed Integer, 64-bit)

Returns: An HDF5 datatype is returned, and is negative if invalid. Complex datatypes should be H5Tclose()'d when done with them.

Example: Get the HDF5 equivalent of the raster type complex-integer-16-bit.
1 hid_t hdf_type;

2

3 hdf_type = GS_ConvertToHDFDatatype(GS_DATATYPE_CI16);

4 if(hdf_type<0) {

5 printf("GS_ConvertToHDFDatatype failure\n");

6 }

hid_t GS_CreateAccessPlist ( void )

GS_CreateAccessPlist creates an HDF5 access parameter list.

The list that GS_CreateAccessPlist() returns is for use when creating or opening an HDF5 file. It sets raw data chunk cache parameters, as well as a driver for file I/O.

See also: GS_FileOpen(), GS_FileCreate()

Returns: This routine returns a valid HDF5 handle to an access_plist, which can be used when creating or opening an HDF5 file.

Example: When creating a new file, we need to specify the access parameters. This routine returns an access list with "typical" parameters and parameter values set for most general uses.
1 hid_t access_plist;

2 access_plist = GS_CreateAccessPlist();

int GS_DataConversion	(	int	in_type,
		const void *	in_buffer,
		int	out_type,
		void *	out_buffer,
		int	nelements
	)

GS_DataConversion converts a data buffer between different types.

See also: GS_DatasetOpen(), GS_DatasetCreate(), GS_DatasetRead()

Parameters

[in]	in_type	The type of data in `in_buffer`. The valid datatypes are: `GS_DATATYPE_UI1` (Unsigned Integer, 1-bit) `GS_DATATYPE_UI8` (Unsigned Integer, 8-bit) `GS_DATATYPE_SI8` (Signed Integer, 8-bit) `GS_DATATYPE_CI8` (Complex Integer, 8-bit (not supported)) `GS_DATATYPE_UI16` (Unsigned Integer, 16-bit) `GS_DATATYPE_SI16` (Signed Integer, 16-bit) `GS_DATATYPE_CI16` (Complex Integer, 16-bit) `GS_DATATYPE_UI32` (Unsigned Integer, 32-bit) `GS_DATATYPE_SI32` (Signed Integer, 32-bit) `GS_DATATYPE_CI32` (Complex Integer, 32-bit) `GS_DATATYPE_CI64` (Complex Integer, 64-bit) `GS_DATATYPE_R32` (Real, 32-bit) `GS_DATATYPE_R64` (Real, 64-bit) `GS_DATATYPE_C64` (Complex, 64-bit) `GS_DATATYPE_C128` (Complex, 128-bit) `GS_DATATYPE_UI64` (Unsigned Integer, 64-bit) `GS_DATATYPE_SI64` (Signed Integer, 64-bit)
[in]	in_buffer	The data we want to convert to a different type.
[in]	out_type	The type of data we want in `out_buffer`. Same valid datatypes as in `in_type`.
[in]	out_buffer	The destination of the converted data from `in_buffer`.
[in]	nelements	The number of elements to convert.

Returns: TRUE on sucess, FALSE on failure.

Example: We have a buffer that is 1000 ints, and we'd like to convert it to doubles.
1 int inbuf[1000];

2 double outbuf[1000];

3 if(!GS_DataConversion(GS_DATATYPE_SI32,inbuf,

4 GS_DATATYPE_R64, outbuf,1000)){

5 printf("data conversion failed\n");

6 }

7 ...here use outbuf...

Details: YET: data type conversions....

hid_t GS_DatasetClose ( hid_t id )

GS_DatasetClose closes a dataset in a GeoSci datafile.

See also: GS_DatasetOpen()

Parameters

[in] id A handle for the dataset. Perhaps from GS_DatasetOpen().

Returns: TRUE on sucess, FALSE on failure.

Example: Close an image raster dataset:
1 hid_t raster_id;

2 if(!GS_DatasetClose(raster_id)) {

3 printf("Failed to close dataset.\n");

4 }

hid_t GS_DatasetCopy	(	hid_t	source,
		hid_t	destination_group_id,
		const_bstring	destination_dataset_name
	)

GS_DatasetCopy copies a dataset to an existing Group: this can be in the same group, a different group, or a different file.

See also: GS_DatasetClose(), GS_DatasetOpen()

Parameters

[in]	source	A handle for a dataset.
[in]	destination_group_id	The handle of the destination group.
[in]	destination_dataset_name	The name of the new dataset to create.

Returns: The handle of the new dataset is returned. If it is less than zero, the copy failed.

Example: Copy an image raster dataset to a new group, with a new name ("r3"). We have already opened the destination group.
1 hid_t source_raster_id;

2 hid_t destination_group_id;

3 hid_t raster_id;

4 bstring name = bfromcstr("r3");

5 raster_id = GS_DatasetCopy(source_raster_id, destination_group_id, name);

6 bdestroy(name);

7 if(raster_id < 0) {

8 printf("Failed to copy dataset.\n");

9 }

hid_t GS_DatasetCreate	(	hid_t	source,
		const_bstring	name,
		int	datatype,
		int	ndims,
		int *	size,
		int	is_extendable,
		int	is_compressed
	)

GS_DatasetCreate creates a dataset in a GeoSci datafile.

See also: GS_DatasetOpen(), GS_DatasetClose()

Parameters

[in]	source	A handle for the file or other container within which to create the dataset.
[in]	name	The name of the dataset to create.
[in]	datatype	The datatype of the numbers to store. Must be one of: `GS_DATATYPE_UI1` (Unsigned Integer, 1-bit) `GS_DATATYPE_UI8` (Unsigned Integer, 8-bit) `GS_DATATYPE_SI8` (Signed Integer, 8-bit) `GS_DATATYPE_CI8` (Complex Integer, 8-bit (not supported)) `GS_DATATYPE_UI16` (Unsigned Integer, 16-bit) `GS_DATATYPE_SI16` (Signed Integer, 16-bit) `GS_DATATYPE_CI16` (Complex Integer, 16-bit) `GS_DATATYPE_UI32` (Unsigned Integer, 32-bit) `GS_DATATYPE_SI32` (Signed Integer, 32-bit) `GS_DATATYPE_CI32` (Complex Integer, 32-bit) `GS_DATATYPE_CI64` (Complex Integer, 64-bit) `GS_DATATYPE_R32` (Real, 32-bit) `GS_DATATYPE_R64` (Real, 64-bit) `GS_DATATYPE_C64` (Complex, 64-bit) `GS_DATATYPE_C128` (Complex, 128-bit) `GS_DATATYPE_UI64` (Unsigned Integer, 64-bit) `GS_DATATYPE_SI64` (Signed Integer, 64-bit)
[in]	ndims	The number of dimensions for the dataset.
[in]	size	The (initial) size for each dimension
[in]	is_extendable	Set to TRUE to make the dataset size extendable, set to FALSE to make the dataset size fixed.
[in]	is_compressed	Set to TRUE to make the dataset compressed, set to FALSE to make the dataset uncompressed.

Returns: The handle of the newly-created and opened dataset is returned. If it is less than zero, the creation failed.

Example: Create an image raster dataset, with size 1024X512:
1 hid_t image_id, raster_id;

2 int size[2];

3 size[0]=512;

4 size[1]=1024;

5 bstring name = bfromcstr("r1");

6 raster_id = GS_DatasetCreate(image_id, name,2,size,FALSE,FALSE);

7 bdestroy(name);

8 if(raster_id < 0) {

9 printf("Failed to create dataset.\n");

10 }

int GS_DatasetDelete	(	hid_t	file_id,
		const_bstring	dataset_name
	)

GS_DatasetDelete deletes a a dataset in a GeoSci datafile.

See also: GS_DatasetOpen(), GS_DatasetClose()

Parameters

[in]	id	A handle for the file.
[in]	dataset_name	The name of the dataset in the file. Should start with a "/".

Returns: TRUE on sucess, FALSE on failure.

Example: Delete an image raster dataset named "/Image1/r1":
1 hid_t file_id;

2 bstring name = bfromcstr("/Image1/r1");

3 if(!GS_DatasetDelete(file_id, name)) {

4 printf("Failed to delete dataset.\n");

5 }

6 bdestroy(name);

int GS_DatasetGetBounds	(	hid_t	dataset_id,
		double *	xmin,
		double *	xmax,
		double *	ymin,
		double *	ymax
	)

GS_DatasetGetBounds returns the rectangular bounding coordinates.

See also: GS_DatasetClose(), GS_DatasetOpen(), GS_DatasetGetProjection()

Parameters

[in]	dataset_id	A handle for a dataset.
[out]	xmin
[out]	xmax
[out]	ymin
[out]	ymax	The coordinates are returned with units that are consistent with the projection that is used. Typically the units are decimal degrees or meters.

Returns: TRUE on success, FALSE if there are any errors.

Example: Print the bounds for a particular dataset:
1 hid_t dataset_id;

2 double xmin, xmax, ymin, ymax;

3 if(GS_DatasetGetBounds(dataset_id, &xmin, &xmax, &ymin, &ymax)){

4 printf("X-range: %lf to %lf, Y-range: %lf to %lf\n", xmin,xmax, ymin,ymax);

5 } else {

6 printf("no bounds\n");

7 }

Details: This routine looks at the "bounds" metadata string in order to determine the bounds that go with the data in this group. If this metadata does not exist, or there is an error in obtaining it or parsing it, FALSE is returned. Otherwise, the correct numbers are filled in, and TRUE is returned.

int GS_DatasetGetDatatype	(	hid_t	id,
		const_bstring	name
	)

GS_DatasetGetDatatype returns the GeoSci datatype for data in the Dataset.

See also: GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in]	id	File handle of selected GeoSci file, or object handle of the container for the Dataset.
[in]	object_name	Name of object to query.

Returns: The GeoSci datatype code is returned, and is 0 if there is an error. Valid datatypes are:
GS_DATATYPE_UI1 (Unsigned Integer, 1-bit)
GS_DATATYPE_UI8 (Unsigned Integer, 8-bit)
GS_DATATYPE_SI8 (Signed Integer, 8-bit)
GS_DATATYPE_CI8 (Complex Integer, 8-bit (not supported))
GS_DATATYPE_UI16 (Unsigned Integer, 16-bit)
GS_DATATYPE_SI16 (Signed Integer, 16-bit)
GS_DATATYPE_CI16 (Complex Integer, 16-bit)
GS_DATATYPE_UI32 (Unsigned Integer, 32-bit)
GS_DATATYPE_SI32 (Signed Integer, 32-bit)
GS_DATATYPE_CI32 (Complex Integer, 32-bit)
GS_DATATYPE_CI64 (Complex Integer, 64-bit)
GS_DATATYPE_R32 (Real, 32-bit)
GS_DATATYPE_R64 (Real, 64-bit)
GS_DATATYPE_C64 (Complex, 64-bit)
GS_DATATYPE_C128 (Complex, 128-bit)
GS_DATATYPE_UI64 (Unsigned Integer, 64-bit)
GS_DATATYPE_SI64 (Signed Integer, 64-bit)

Example: Get the GeoSci type code for an image raster Dataset.
1 hid_t image_id;

2 int gs_type;

3 bstring name = bfromcstr("r1");

4 gs_type = GS_DatasetGetDatatype(image_id,name);

5 bdestroy(name);

6 if(!gs_type) {

7 printf("GS_DatasetGetDatatype failure\n");

8 }

int GS_DatasetGetDatatypeByID ( hid_t id )

GS_DatasetGetDatatypeByID returns the GeoSci datatype for the data in the Dataset.

See also: GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in] id Datset handle

Returns: The GeoSci datatype code is returned, and is 0 if there is an error. Valid datatypes are:
GS_DATATYPE_UI1 (Unsigned Integer, 1-bit)
GS_DATATYPE_UI8 (Unsigned Integer, 8-bit)
GS_DATATYPE_SI8 (Signed Integer, 8-bit)
GS_DATATYPE_CI8 (Complex Integer, 8-bit (not supported))
GS_DATATYPE_UI16 (Unsigned Integer, 16-bit)
GS_DATATYPE_SI16 (Signed Integer, 16-bit)
GS_DATATYPE_CI16 (Complex Integer, 16-bit)
GS_DATATYPE_UI32 (Unsigned Integer, 32-bit)
GS_DATATYPE_SI32 (Signed Integer, 32-bit)
GS_DATATYPE_CI32 (Complex Integer, 32-bit)
GS_DATATYPE_CI64 (Complex Integer, 64-bit)
GS_DATATYPE_R32 (Real, 32-bit)
GS_DATATYPE_R64 (Real, 64-bit)
GS_DATATYPE_C64 (Complex, 64-bit)
GS_DATATYPE_C128 (Complex, 128-bit)
GS_DATATYPE_UI64 (Unsigned Integer, 64-bit)
GS_DATATYPE_SI64 (Signed Integer, 64-bit)

Example: Get the GeoSci type code for the data in an image raster Dataset.
1 hid_t dataset_id;

2 int gs_type;

3 gs_type = GS_DatasetGetDatatypeByID(dataset_id);

4 if(!gs_type) {

5 printf("GS_DatasetGetDatatypeByID failure\n");

6 }

bstring GS_DatasetGetDatum ( hid_t dataset_id )

GS_DatasetGetDatum returns a description of the relevant datum if one exists.

See also: GS_DatasetClose(), GS_DatasetOpen()

Parameters

[in] dataset_id A handle for a dataset.

Returns: A string describing the datum that is used for the data in this dataset. "No Datum" is returned if the datum cannot be determined, or on any other error. This string should be bdestroy()'d when finished with it.

Example: Print the datum for a particular dataset:
1 hid_t dataset_id;

2 bstring datum;

3 datum = GS_DatasetGetDatum(dataset_id);

4 printf("%s\n",bdata(datum));

5 bdestroy(datum);

Details: This routine looks at the "spatialref" metadata string in order to determine the datum that is being used. If the spatialref metadata item does not exist, then "No Datum" is returned. If the spatialref metadata item exists, then the routine looks for the keyword "DATUM" which should appear in the WKT portion of this metadata. If it is not found, then "No Datum" is returned, otherwise the string that follows this keyword is returned.

int GS_DatasetGetDimensions	(	hid_t	id,
		const_bstring	name,
		long int **	size
	)

GS_DatasetGetDimensions returns the current dimensions for the Dataset.

See also: GS_DatasetGetDatatype(), GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in]	id	File handle of selected GeoSci file, or object handle of the container for the Dataset.
[in]	name	Name of object to query.
[out]	size	A vector of long integers: the size of each dimension: the number of data-objects per dimension.

Returns: The number of dimensions in the Dataset, or zero if there is an error. Also returns the length of each dimension (number of data-objects), in the integer vector size. This vector is allocated by this function, and should be GFree()'d when done with it.

Example: Get the size of an image raster Dataset.
1 hid_t image_id;

2 int ndims;

3 long int *size;

4 bstring name = bfromcstr("r1");

5 ndims = GS_DatasetGetDimensions(image_id,name,&size);

6 bdestroy(name);

7 if(!ndims) {

8 printf("GS_DatasetGetDimensions failure\n");

9 }

10 printf("the dataset has %d dimensions:\n",ndims);

11 for(i=0;i<ndims;i++)

12 printf("dimension %d size is: %d data-objects\n",i+1,size[i]);

13 GFree(size);

Details: Note that this function returns dimensions in terms of the number of data-objects. It does NOT return the size in bytes.

int GS_DatasetGetDimensionsByID	(	hid_t	id,
		long int **	size
	)

GS_DatasetGetDimensionsByID returns the current dimensions for the Dataset.

See also: GS_DatasetGetDimensions(), GS_DatasetGetDatatype(), GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in]	id	object handle of the Dataset.
[out]	size	A vector of long integers: the size of each dimension: the number of data-objects per dimension.

Returns: The number of dimensions in the Dataset, or zero if there is an error. Also returns the length of each dimension (number of data-objects), in the integer vector size. This vector is allocated by this function, and should be GFree()'d when done with it.

Example: Get the size of an image raster Dataset.
1 hid_t raster_id;

2 int ndims;

3 long int *size;

4 ndims = GS_DatasetGetDimensionsByID(raster_id,&size);

5 if(!ndims) {

6 printf("GS_DatasetGetDimensionsByID failure\n");

7 }

8 printf("the dataset has %d dimensions:\n",ndims);

9 for(i=0;i<ndims;i++)

10 printf("dimension %d size is: %ld data-objects\n",i+1,size[i]);

11 GFree(size);

Details: Note that this function returns dimensions in terms of the number of data-objects. It does NOT return the size in bytes.

hid_t GS_DatasetGetParent ( hid_t id )

GS_DatasetGetParent returns the parent object-id for a Dataset.

Parameters

[in] id The handle of the Dataset.

Returns: Returns the object-id of the parent object (>=0), or ERROR (-1) on failure.

Example: Get the parent of a Dataset.
1 hid_t dataset_id, object_id;

2 object_id = GS_DatasetGetParent(dataset_id);

3 if(object_id < 0){

4 printf("Could not open the parent of the Dataset.\n");

5 }

bstring GS_DatasetGetProjection ( hid_t dataset_id )

GS_DatasetGetProjection returns a description of the relevant projection.

See also: GS_DatasetClose(), GS_DatasetOpen()

Parameters

[in] dataset_id A handle for a dataset.

Returns: A string describing the projection that is used for the data in this dataset. "No Projection" is returned if the projection cannot be determined, or on any other error. This string should be bdestroy()'d when finished with it.

Example: Print the projection for a particular dataset:
1 hid_t dataset_id;

2 bstring projection;

3 projection = GS_DatasetGetProjection(dataset_id);

4 printf("%s\n",bdata(projection));

5 bdestroy(projection);

Details: This routine looks at the "spatialref" metadata string in order to determine the projection that is being used. If the spatialref metadata item does not exist, then "No Projection" is returned. If the spatialref metadata item exists, then the routine looks for the keyword "PROJCS" which should appear in the WKT portion of this metadata. If it is found, the string that follows this keyword is returned. If it is not found, then the routine looks for the keyword "GEOGCS" which should appear in the WKT portion of this metadata. If it is found, then the string "Geographic" is returned, otherwise the string "No Projection" is returned.

int GS_DatasetGetType ( hid_t dataset_id )

GS_DatasetGetType returns the type of a GeoSci Dataset.

See also: GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in] dataset_id A handle for the dataset.

Returns: The dataset type code is returned on success:
GS_OBJECT_TYPE_IFILE (10)
GS_OBJECT_TYPE_RASTER (9)
GS_OBJECT_TYPE_METADATA_DATASET (12)
GS_OBJECT_TYPE_METADATA_IFILE (13)

On failure, the following type code is returned:
GS_OBJECT_TYPE_UNKNOWN (0)

Example: Get the type of an image raster dataset:
1 hid_t raster_id;

2

3 if(GS_DatasetGetType(raster_id) != GS_OBJECT_TYPE_RASTER ) {

4 printf("Dataset is not a raster.\n");

5 }

int GS_DatasetIsWriteable	(	hid_t	file_id,
		const_bstring	dataset_name
	)

GS_DatasetIsWriteable returns if dataset is writeable or not.

See also: GS_DatasetOpen(), GS_DatasetClose()

Parameters

[in]	id	A handle for the file.
[in]	dataset_name	The name of the dataset in the file. Should start with a "/".

Returns: TRUE if the dataset is writeable, FALSE otherwise.

Example: Determine if a image raster dataset named "/Image1/r1" is writeable or not:
1 hid_t file_id;

2 bstring name = bfromcstr("/Image1/r1");

3 if(GS_DatasetIsWriteable(file_id, name)) {

4 printf("It is writeable\n");

5 } else {

6 printf("It is not writeable\n");

7 }

8 bdestroy(name);

int GS_DatasetIsWriteableByID ( hid_t id )

GS_DatasetIsWriteableByID returns if dataset is writeable or not.

See also: GS_DatasetOpen(), GS_DatasetClose()

Parameters

[in] id A handle for the dataset.

Returns: TRUE if the dataset is writeable, FALSE otherwise.

Example: Determine if a previously-opened image raster dataset named "/Image1/r1" is writeable or not:
1 hid_t id;

2 if(GS_DatasetIsWriteableByID(id)) {

3 printf("It is writeable\n");

4 } else {

5 printf("It is not writeable\n");

6 }

hid_t GS_DatasetOpen	(	hid_t	source,
		const_bstring	name
	)

GS_DatasetOpen opens a dataset in a GeoSci datafile.

See also: GS_DatasetClose()

Parameters

[in]	source	A handle for a file or other container that has a dataset in it.
[in]	name	The name of the dataset to open.

Returns: The handle of the opened dataset is returned. If it is less than zero, the open failed.

Example: Open an image raster dataset:
1 hid_t image_id, raster_id;

2 bstring name = bfromcstr("r1");

3 raster_id = GS_DatasetOpen(image_id, name);

4 if(raster_id < 0) {

5 printf("Failed to open dataset.\n");

6 }

7 bdestroy(name);

int GS_DatasetRead	(	hid_t	dataset_id,
		const long int *	offsets,
		const long int *	sizes,
		int	datatype,
		void *	buffer
	)

GS_DatasetRead reads data from a dataset.

See also: GS_DatasetWrite(), GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in]	id	A handle for the dataset. Perhaps from GS_DatasetOpen().
[in]	offsets	Must supply an offset to the first data element to read for each dimension. Zero offset is used for reading starting with the first data-element.
[in]	sizes	Must supply how many data elements to read for each dimension. Zero offset is used for reading starting with the first data-element. Using the offset and size for each dimension allows the specification of rectangular windows in n-dimensional space. For example, in 2-dimensions the window is: xoffset = offset[0], yoffset= offset[1] xsize = sizes[0], ysize = sizes[1]
[in]	datatype	The datatype of the buffer. All the data that is read is converted to this datatype, and then returned to the caller in `buffer`. See the Details section for how this conversion is done. The valid datatypes are: `GS_DATATYPE_UI1` (Unsigned Integer, 1-bit) `GS_DATATYPE_UI8` (Unsigned Integer, 8-bit) `GS_DATATYPE_SI8` (Signed Integer, 8-bit) `GS_DATATYPE_CI8` (Complex Integer, 8-bit (not supported)) `GS_DATATYPE_UI16` (Unsigned Integer, 16-bit) `GS_DATATYPE_SI16` (Signed Integer, 16-bit) `GS_DATATYPE_CI16` (Complex Integer, 16-bit) `GS_DATATYPE_UI32` (Unsigned Integer, 32-bit) `GS_DATATYPE_SI32` (Signed Integer, 32-bit) `GS_DATATYPE_CI32` (Complex Integer, 32-bit) `GS_DATATYPE_CI64` (Complex Integer, 64-bit) `GS_DATATYPE_R32` (Real, 32-bit) `GS_DATATYPE_R64` (Real, 64-bit) `GS_DATATYPE_C64` (Complex, 64-bit) `GS_DATATYPE_C128` (Complex, 128-bit) `GS_DATATYPE_UI64` (Unsigned Integer, 64-bit) `GS_DATATYPE_SI64` (Signed Integer, 64-bit)
[out]	buffer	This is a pointer to enough memory to hold the data that is being read.

Returns: TRUE on sucess, FALSE on failure.

Example: We have a 2D dataset named "d4", Read in from data elements 0 to 500 in dimension 1, and from data elements 100 to 700 in dimension 2. The data is stored as integers, but we'd like to read them as doubles.
1 hid_t group_id;

2 hid_t dataset_id;

3 double buffer[500*600];

4 int offsets[10], sizes[10];

5 bstring name = bfromcstr("d4");

6 dataset_id = GS_DatasetOpen(group_id,name);

7 if(dataset_id < 0){

8 printf("Failed to open dataset\n");

9 bdestroy(name);

10 return;

11 }

12 bdestroy(name);

13 offsets[0]=0;

14 offsets[1]=100;

15 sizes[0]=500;

16 sizes[1]=600;

17 if(!GS_DatasetRead(dataset_id, offsets, sizes,

18 GS_DATATYPE_R64, (void *)buffer)) {

19 printf("Failed to read from dataset.\n");

20 }

Details: YET: data type conversions....
YET: deal with interleaving spec.....
YET: indexing...

int GS_DatasetRename	(	hid_t	group_id,
		const_bstring	oldname,
		const_bstring	newname
	)

GS_DatasetRename renames a dataset in a GeoSci datafile.

Parameters

[in]	group_id	A handle for the container of the dataset. This should be a group.
[in]	oldname	Current name of dataset to rename.
[in]	newname	Desired new name of the dataset.

Returns: TRUE on sucess, FALSE on failure.

Example: Rename a dataset from "r1" to "r4".
1 hid_t group_id;

2 bstring oldname = bfromcstr("r1");

3 bstring newname = bfromcstr("r2");

4 if(!GS_GS_DatasetRename(group_id, oldname, newname) ) {

5 printf("Failed to rename the dataset.\n");

6 }

7 bdestroy(oldname);

8 bdestroy(newname);

bstring GS_DatasetReport ( hid_t dataset_id )

GS_DatasetReport returns a brief description of the dataset.

See also: GS_DatasetClose(), GS_DatasetOpen()

Parameters

[in] dataset_id A handle for a dataset.

Returns: A string that provides a brief overview of the dataset. The string is zero-length on any error. Always bdestroy() the string when done with it.

Example: Get a report string on an image raster dataset.
1 hid_t raster_id;

2 bstring the_report;

3 the_report = GS_DatasetReport(raster_id);

4 printf("Report for the dataset: %s\n",bdata(the_report));

5 bdestroy(the_report);

Details: For an image raster, the report string looks like the following:
1 [Raster] Landsat-Washita-SMEX3: Channel02; UINT8, 1024 X 4096

2 WGS84, UTM16T, X-Range: 274716.95 to 275716.95, Y-Range: 4684434.95 to 4684534.95

or more generally:
1 [dataset-type] name: descriptor; datatype, dx X dy

2 Datum, Projection, Bounds

where the first string is the type of dataset, which, besides "Raster", could include: "Internal File", "Metadata", "Metadata/Internal-File", or "Unknown". The second string is the name of the Dataset, while the third is the descriptor. The next one is the datatype. See GS_DatatypeAsString() for a list of possible datatypes. The last string is the dimensions of the raster: dx X dy. For non-image rasters, the dimensions are 1-deminsional, and there are no Datum, Projection, or Bounds entries. NOTE: so far this only works for Image Rasters.

int GS_DatasetSetType	(	hid_t	dataset_id,
		int	typecode
	)

GS_DatasetSetType set the type of a dataset in a GeoSci file.

Parameters

[in]	dataset_id	A handle for the dataset.
[in]	typecode	An integer type code specifying the type of dataset. One of: GS_OBJECT_TYPE_IFILE 10 GS_OBJECT_TYPE_RASTER 9 GS_OBJECT_TYPE_METADATA_DATASET 12 GS_OBJECT_TYPE_METADATA_IFILE 13

Returns: TRUE on sucess, FALSE on failure.

Example: Set the type of an image raster dataset:
1 hid_t raster_id;

2 if(!GS_DatasetSetType(raster_id, GS_OBJECT_TYPE_RASTER) ) {

3 printf("Failed to set the type of the dataset.\n");

4 return;

5 }

int GS_DatasetWrite	(	hid_t	dataset_id,
		const long int *	offsets,
		const long int *	sizes,
		int	datatype,
		const void *	buffer
	)

GS_DatasetWrite writes data to a dataset.

See also: GS_DatasetRead(), GS_DatasetOpen(), GS_DatasetCreate()

Parameters

[in]	id	A handle for the dataset. Perhaps from GS_DatasetOpen().
[in]	offsets	Must supply an offset to the first data element to write for each dimension. Zero offset is used for writing starting with the first data-element.
[in]	sizes	Must supply how many data elements to write for each dimension. Zero offset is used for writing starting with the first data-element. Using the offset and size for each dimension allows the specification of rectangular windows in n-dimensional space. For example, in 2-dimensions the window is: xoffset = offset[0], yoffset= offset[1] xsize = sizes[0], ysize = sizes[1]
[in]	datatype	The datatype of the buffer. All the data that is written is converted from this datatype, to the datatype used by the Dataset. See the Details section for how this conversion is done. The valid datatypes are: `GS_DATATYPE_UI1` (Unsigned Integer, 1-bit) `GS_DATATYPE_UI8` (Unsigned Integer, 8-bit) `GS_DATATYPE_SI8` (Signed Integer, 8-bit) `GS_DATATYPE_CI8` (Complex Integer, 8-bit (not supported)) `GS_DATATYPE_UI16` (Unsigned Integer, 16-bit) `GS_DATATYPE_SI16` (Signed Integer, 16-bit) `GS_DATATYPE_CI16` (Complex Integer, 16-bit) `GS_DATATYPE_UI32` (Unsigned Integer, 32-bit) `GS_DATATYPE_SI32` (Signed Integer, 32-bit) `GS_DATATYPE_CI32` (Complex Integer, 32-bit) `GS_DATATYPE_CI64` (Complex Integer, 64-bit) `GS_DATATYPE_R32` (Real, 32-bit) `GS_DATATYPE_R64` (Real, 64-bit) `GS_DATATYPE_C64` (Complex, 64-bit) `GS_DATATYPE_C128` (Complex, 128-bit) `GS_DATATYPE_UI64` (Unsigned Integer, 64-bit) `GS_DATATYPE_SI64` (Signed Integer, 64-bit)
[out]	buffer	This is a pointer to enough memory to hold the data that is being written.

Returns: TRUE on sucess, FALSE on failure.

Example: We have a 2D dataset named "d4", Write to data elements 0 to 500 in dimension 1, and to data elements 100 to 700 in dimension 2. The data is stored in the Dataset as integers, and we are sending doubles, which therefore need to be converted.
1 hid_t group_id;

2 hid_t dataset_id;

3 double buffer[500*600];

4 int offsets[10], sizes[10];

5 dataset_id = GS_DatasetOpen(group_id,"d4");

6 if(dataset_id < 0){

7 printf("Failed to open dataset\n");

8 return;

9 }

10 offsets[0]=0;

11 offsets[1]=100;

12 sizes[0]=500;

13 sizes[1]=600;

14 if(!GS_DatasetWrite(dataset_id, offsets, sizes,

15 GS_DATATYPE_R64, (void *)buffer)) {

16 printf("Failed to write to dataset.\n");

17 }

Details: YET: data type conversions....
YET: deal with interleaving spec.....
YET: indexing...

bstring GS_DatatypeAsString ( int datatype )

GS_DatatypeAsString return a string representing the datatype.

See also: GS_DatatypeAsInteger(), GS_DatatypeNumbytes()

Parameters

[in] datatype An integer representing a GeoSci datatype. Valid datatypes:
GS_DATATYPE_UI1 1 A single bit
GS_DATATYPE_UI8 2 Unsigned 8-bit integer
GS_DATATYPE_SI8 3 Signed 8-bit integer
GS_DATATYPE_CI8 4 Complex 8-bit integer
GS_DATATYPE_UI16 5 Unsigned 16-bit integer
GS_DATATYPE_SI16 6 Signed 16-bit integer
GS_DATATYPE_CI16 7 Complex 16-bit integer
GS_DATATYPE_UI32 8 Unsigned 32-bit integer
GS_DATATYPE_SI32 9 Signed 32-bit integer
GS_DATATYPE_CI32 10 Complex 32-bit integer
GS_DATATYPE_CI64 11 Complex 64-bit integer
GS_DATATYPE_R32 12 32-bit Real number
GS_DATATYPE_R64 13 64-bit Real number
GS_DATATYPE_C64 14 Complex 64-bit floating-point number
GS_DATATYPE_C128 15 Complex 128-bit floating point
GS_DATATYPE_UI64 16 Unsigned 64-bit integer
GS_DATATYPE_SI64 17 Signed 64-bit integer

Returns: The valid bstring is returned always. It has a non-zero length on success, zero length on failure. Need to bdestroy() it when done.

Example: Print the datatype of a raster channel:
1 int raster_datatype;

2 bstring thetype = GS_DatatypeAsString(raster_datatype);

3 if(bstrlen(thetype)>0) {

4 printf("The datatype is %s\n",bdata(thetype));

5 } else {

6 printf("The datatype is unknown.\n");

7 }

8 bdestroy(thetype);

int GS_DatatypeIsComplex ( int datatype )

GS_DatatypeIsComplex returns TRUE if a complex datatype.

See also: GS_DatatypeAsString(), GS_DatatypeIsInteger(), GS_DatatypeAsInteger(), GS_DatatypeNumbytes()

Parameters

[in] datatype An integer representing a GeoSci datatype. Valid datatypes:
GS_DATATYPE_UI1 1 A single bit
GS_DATATYPE_UI8 2 Unsigned 8-bit integer
GS_DATATYPE_SI8 3 Signed 8-bit integer
GS_DATATYPE_CI8 4 Complex 8-bit integer
GS_DATATYPE_UI16 5 Unsigned 16-bit integer
GS_DATATYPE_SI16 6 Signed 16-bit integer
GS_DATATYPE_CI16 7 Complex 16-bit integer
GS_DATATYPE_UI32 8 Unsigned 32-bit integer
GS_DATATYPE_SI32 9 Signed 32-bit integer
GS_DATATYPE_CI32 10 Complex 32-bit integer
GS_DATATYPE_CI64 11 Complex 64-bit integer
GS_DATATYPE_R32 12 32-bit Real number
GS_DATATYPE_R64 13 64-bit Real number
GS_DATATYPE_C64 14 Complex 64-bit floating-point number
GS_DATATYPE_C128 15 Complex 128-bit floating point
GS_DATATYPE_UI64 16 Unsigned 64-bit integer
GS_DATATYPE_SI64 17 Signed 64-bit integer

Returns: TRUE is returned for complex datatypes, FALSE for others, and ERROR otherwise.

Example: Determine if a datatype is complex:
1 int datatype;

2 if(GS_DatatypeIsComplex(datatype)==TRUE){

3 printf("the datatype is complex.\n);

4 } else {

5 printf("the datatype is not complex\n");

6 }

Note that if one does not compare with TRUE, but instead uses the default C behavior of anything not 0 being true: both TRUE and ERROR are non-zero and so one may not get the expected behavior.

char* GS_Dirname ( const char * name )

Dirname returns the directory name for a UNIX pathname.

See also: GS_FileOpen(), GS_GroupCreate()

Parameters

[in] name The name of an object in an existing GeoSci file. Use Unix filenaming conventions, giving the full pathname, starting with "/".

Returns: A character string is returned with the directory part of the name which does not end in a '/'. GFree() it when done. If there are errors, a NULL pointer is returned.

Example: 1 char *dir;

2

3 dir = Dirname("/groupa/group1/image4");

4 if(!dir){

5 printf("Dirname failed\n");

6 exit(-1);

7 }

8

9 ...use dir here....

10

11 GFree(dir);

int GS_FileClose ( hid_t file_id )

GS_FileClose closes a GeoSci datafile.

See also: GS_FileOpen()

Parameters

[in] file_id File handle for GeoSci file to be closed.

Returns: TRUE is returned on success, while FALSE is returned on failure.

Example: This example opens and then closes a standard GeoSci file:
1 hid_t file_id;

2 bstring filename = bfromcstr("testimage.hd5");

3 bstring access = bfromcstr("r+");

4 file_id = GS_FileOpen( filename, access );

5 bdestroy(filename);

6 bdestroy(access);

7 ... use the file ...

8 GS_FileClose( file_id );

int GS_FileCloseAllObjects ( hid_t id )

GS_FileCloseAllObjects closes all open objects in a file.

See also: GS_FileClose(), GS_FileOpen()

Parameters

[in] id The handle of the open file, or any object in the file.

Returns: TRUE is returned on success, FALSE otherwise.

Example: Close all objects in an already-open file:
1 hid_t file_id;

2 if(GS_FileCloseAllObjects( file_id )){

3 printf("success.\n");

4 } else {

5 printf("failure.\n");

6 }

int GS_FileCommitDatatypes ( hid_t file_id )

GS_FileCommitDatatypes commits the complex raster datatypes to a file.

See also: GS_FileCreate()

Parameters

[in] file_id The file ID

Returns: TRUE on success, FALSE on failure.

Example:: After creating a new file, commit the complex raster datatypes to it:
1 hid_t file_id;

2 if(!GS_FileCommitDatatypes(file_id)){

3 printf("failed to commit the complex raster datatypes to the file\n");

4 }

Details: HDF-5 requires user-created raster datatypes to be "committed" to a file where these datatypes are used. Since all the complex raster datatypes used in GeoSci are "user-created", we need to make sure that they are always committed.

int GS_FileCopy	(	bstring	oldname,
		bstring	newname
	)

GS_FileCopy copies a GeoSci datafile to a new file.

See also: GS_FileRename()

Parameters

[in]	oldname	Name of existing file to copy.
[in]	newname	Name of new file to create and copy into.

Returns: TRUE is returned on success, FALSE on failure.

Example: Copy a file named "testimage.hd5" to "sirc_april.hd5".
1 bstring filename1 = bfromcstr("testimage.hd5");

2 bstring filename2 = bfromcstr(sirc_april.hdf5");

3 if(!GS_FileCopy( filename1, filename2 )){

4 printf("GS_FileCopy failure.\n");

5 }

6 bdestroy(filename1);

7 bdestroy(filename2);

Details: GS_FileCopy() will return an error if the file is open, or if a file with the same destination name already exists.

hid_t GS_FileCreate ( const_bstring filename )

GS_FileCreate creates an empty GeoSci datafile.

The basic file metadata is created, but nothing else. GS_FileCreate() assumes the file does NOT exist before creating it, and will return an error if a file with the same name already exists.

See also: GS_FileOpen(), GS_ImageGeorefIO()

Parameters

[in] filename Name of file to be created. If there is no ".hd5" extension, this routine will create a file with the ".hdf5" extension.

Returns: The routine returns a file handle on success, which is negative if creation fails.

Example: Create an empty file named "testimage.hd5".
1 hid_t file_id;

2 bstring filename=bfromcstr("testimage.hd5");

3 file_id = GS_FileCreate( filename );

4 ... use the file ...

5 GS_FileClose( file_id );

Details: For every GeoSci file we create we also "commit" every complex datatype into it. That way, no matter what a user does, the datatypes are there for them to use. This simplifies the other codes, who now need not be concerned about dealing with this.

int GS_FileCreateMetadata	(	hid_t	file_id,
		const_bstring	descriptor
	)

GS_FileCreateMetadata Creates metadata in a GeoSci datafile.

GS_FileCreateMetadata() creates a new metadata group to store per-file metadata in, it then fills them in with default values, and the file descriptor string that is passed in.

See also: FileCreate()

Parameters

[in]	file_id	The file ID
[in]	descriptor	A character string describing the file contents.

Returns: TRUE on success, FALSE on failure.

Example:: Create a new file named "av1.h5" and set it's file metadata, in particular make the file descriptor string be "Aviris over Boston, MA".
1 hid_t file_id;

2 bstring filename = bfromcstr("av1.h5");

3 file_id = GS_FileCreateEmpty(filename);

4 bdestroy(filename);

5 if(file_id > 0) {

6 bstring description = bfromcstr("Aviris over Boston, MA");

7 if(GS_FileCreateMetadata(file_id,description){

8 printf("success\n");

9 }

10 bdestroy(description);

11 }

Details:

The file metadata is stored in a group named "/_Header". The file metadata items are: grouptype (= "Metadata"), filetype (= "GEOSCI"), software_version (= "V0.0.1"), creation_datetime, last_update_datetime, history, and descriptor, the last one being set by a call to this function.

Note that until the file metadata is set up correctly the file is not recognized as a valid GeoSci file, and so most functions in this library will not operate on it successfully. Because of this, the file creation function, GS_FileCreate, calls this function as part of the file creation process.

int GS_FileDelete ( const_bstring filename )

GS_FileDelete deletes an existing GeoSci datafile.

See also: GS_FileCreate(), GS_FileRename()

Parameters

[in] filename Name of existing file to delete.

Returns: TRUE is returned on success, FALSE on failure.

Example: Delete a file named "testimage.hd5".
1 bstring filename = bfromcstr("testimage.hd5");

2 if(!GS_FileDelete( filename )){

3 printf("GS_FileDelete failure.\n");

4 } else {

5 printf("GS_FileDelete succeeded.\n");

6 }

7 bdestroy(filename);

Details: GS_FileDelete() will return an error if the file is open.

int GS_FileFlush ( hid_t object_id )

GS_FileFlush forces the datafile to be updated.

GS_FileFlush() forces all changes to a file to be flushed to the hard drive, forcing them to occur rather than waiting in a "buffered" state.

See also: GS_FileOpen(), GS_FileClose()

Parameters

[in] object_id ID of a file, an image, or any other valid object in a GeoSci datafile.

Returns: Returns TRUE on success, FALSE otherwise.

Example: After writing to an image, make sure all changes are written to disk.
1 hid_t image_id;

2 bstring image_name=bfromcstr("Image3");

3 image_id=GS_ImageOpen(file_id,image_name);

4 bdestroy(image_name);

5 ... modify the image ....

6 GS_FileFlush(image_id);

Note that we could have used file_id as well.

int GS_FileIsOpen ( const_bstring filename )

GS_FileIsOpen determines if a GeoSci datafile is already open in the current process.

See also: GS_FileOpen(), GS_FileRename()

Parameters

[in] filename Name of existing file to query.

Returns: TRUE is returned if the file is open, FALSE otherwise.

Example: See if a file named "testimage.hd5" is open.
1 bstring filename = bfromcstr("testimage.hd5");

2 if(GS_FileIsOpen( filename)){

3 printf("testimage.hd5 is already open.\n");

4 } else {

5 printf("testimage.hd5 is NOT open.\n");

6 }

7 bdestroy(filename);

Details: GS_FileIsOpen() is not able to say if another process has opened the file.

int GS_FileIsWriteable ( hid_t id )

GS_FileIsWriteable returns if file is writeable or not.

See also: GS_ObjectLock(), GS_ObjectUnlock()

Parameters

[in] id The handle of the file, or any object in the file.

Returns: Returns TRUE if the file associated with the given handle is writeable, or FALSE if not. Returns ERROR (-1) if cannot determine the status.

Example: 1 int status;

2 ...

3 status = GS_FileIsWriteable(file_id);

4 if(status < 0){

5 printf("Could not determine read/write status of file.\n");

6 return;

7 }

8 if(status==FALSE) return;

9 ...here we can write to the file....

Details: A file is writeable if it was opened in read/write mode using GS_FileOpen, and if the writeable metadata is TRUE, which can be changed via a call to GS_ObjectLock, and GS_objectUnlock.

hid_t GS_FileOpen	(	const_bstring	dbname,
		const_bstring	access
	)

GS_FileOpen opens a GeoSci datafile.

See also: GS_FileCreate(), GS_FileClose()

Parameters

[in]	dbname	The name of the GeoSci datafile to be opened.
[in]	access	Read/Write flag: "r" : Open file for Read only "r+": Open file for Read/Write

Returns: Returns the hid_t file handle for the file opened. If the GeoSci file does not exist, a negative file handle is returned, and the global error_string is set.

Example: Open a file named "testimage.hd5" for read/write. Note that the default extension ".hd5" is tried by GS_FileOpen() if the file "testimage" does not exist.
1 hid_t file_id;

2 bstring filename= bfromcstr("testimage");

3 bstring access = bfromcstr("r+");

4 file_id = GS_FileOpen ( filename, access);

5 bdestroy(filename);

6 bdestroy(access);

7 ... use the file ...

8 GS_FileClose (file_id);

int GS_FileRename	(	const_bstring	oldname,
		const_bstring	newname
	)

GS_FileRename renames an existing GeoSci datafile.

See also: GS_FileCreateEmpty(), GS_FileCopy()

Parameters

[in]	oldname	Name of existing file to rename.
[in]	newname	New name to be assigned to file 'oldname'.

Returns: TRUE is returned on success, FALSE on failure.

Example: Rename a file named "testimage.hd5" to "sirc_april.hd5".
1 bstring oldname = bfromcstr("testimage.hd5");

2 bstring newname = bfromcstr("sirc_april.hd5");

3 if(!GS_FileRename( oldname, newname )){

4 printf("GS_FileRename failure.\n");

5 }

6 bdestroy(oldname);

7 bdestroy(newname);

Details: GS_FileRename() will return an error if the file is open, or if a file with the same newname already exists.

int GS_FileReport	(	const_bstring	filename,
		bstring	report_string
	)

GS_FileReport summarizes the contents of a GeoSci datafile.

Parameters

[in]	filename	Name of datafile to be queried.
[in]	report_string	The returned report, as a multi-line string. On entry, must be a valid bstring.

Returns: Returns TRUE on success, FALSE on failure. The report_string contains a multi-line string with contents like the following:
Filename: test123.h5 [RW], Empty File
Created: 19:37:45 23-Jun-2016 , Last Update: 19:37:45 23-Jun-2016
image_aa: [Image] SIR-C Raco 102.4 SRL-1

Example: Obtain report on a file named "testimage.hd5".
1 bstring report_string=bfromcstr("");

2 bstring filename = bfromcstr("testimage.hd5");

3 if(GS_FileReport(filename,report_string)){

4 printf("%s",report_string);

5 } else {

6 printf("%s\n",error_string);

7 }

8 bdestroy(filename);

9 bdestroy(report_string);

bstring GS_GetFilename ( hid_t id )

GetFilename returns the filename associated with an ID.

Parameters

[in] id The handle of the file, or any object in the file.

Returns: Returns a character string of the filename within which the given handle is defined, or a zero-length bstring if there is any kind of error. bdestroy() it when done.

Example: 1 bstring the_filename= bfromcstr("");

2 ...

3 the_filename = GS_GetFilename(file_id);

4 if(bstrlen(the_filename)==0){

5 printf("Could not determine the filename\n");

6 bdestroy(the_filename);

7 return;

8 }

9 printf("The filename is: %s\n",bdata(the_filename));

10 bdestroy(the_filename);

bstring GS_GetIDName ( hid_t id )

GetIDName returns the name of the given handle.

Parameters

[in] id The handle of the file, or any object in the file.

Returns: Returns a character string (bstring) of the object name of the given handle, or a zero-length bstring if there is any kind of error. bdestroy() it when done.

Example: 1 bstring the_name = bfromcstr("");

2 ...

3 the_name = GS_GetIDName(id);

4 if(bstrlen(the_name)==0){

5 printf("Could not determine the object name\n");

6 bdestroy(the_name);

7 return;

8 }

9 printf("The object name is: %s\n",bdata(the_name));

10 bdestroy(the_name);

bstring GS_GetRasterTypeAsString ( int datatype )

GS_GetRasterTypeAsString returns a string representing the datatype.

See also: GS_GetRasterTypeAsInteger, GS_GetRasterTypeNumbytes

Parameters

[in] datatype An integer representing a GeoSci raster datatype. Valid datatypes:
GS_DATATYPE_UI1 1 A single bit
GS_DATATYPE_UI8 2 Unsigned 8-bit integer
GS_DATATYPE_SI8 3 Signed 8-bit integer
GS_DATATYPE_CI8 4 Complex 8-bit integer
GS_DATATYPE_UI16 5 Unsigned 16-bit integer
GS_DATATYPE_SI16 6 Signed 16-bit integer
GS_DATATYPE_CI16 7 Complex 16-bit integer
GS_DATATYPE_UI32 8 Unsigned 32-bit integer
GS_DATATYPE_SI32 9 Signed 32-bit integer
GS_DATATYPE_CI32 10 Complex 32-bit integer
GS_DATATYPE_CI64 11 Complex 64-bit integer
GS_DATATYPE_R32 12 32-bit Real number
GS_DATATYPE_R64 13 64-bit Real number
GS_DATATYPE_C64 14 Complex 64-bit floating-point number
GS_DATATYPE_C128 15 Complex 128-bit floating point
GS_DATATYPE_UI64 16 Unsigned 64-bit integer
GS_DATATYPE_SI64 17 Signed 64-bit integer

Returns: The bstring is returned on success, or a zero-length bstring on failure. bdestroy() it when done.

Example: Get a string represenation of the raster type GS_DATATYPE_R64:
1 bstring str = bfromcstr("");

2 bassignstr(str,GS_GetRasterTypeAsString(GS_DATATYPE_R64));

3 printf("the string is: %s\n",bdata(str));

4 bdestroy(str);

int GS_GetStringAttribute	(	hid_t	object_id,
		const_bstring	name,
		bstring	value
	)

GS_GetStringAttribute reads a string attribute from an object and returns its value.

Parameters

[in]	object_id	The opened object where the attribute is stored.
[in]	name	The name of the attribute variable.
[in]	value	The returned value of the variable. On input, this must be a valid bstring.

Returns: TRUE on success, FALSE on failure

Example:: Read the group type attribute:
1 bstring group_type=bfromcstr("");

2 bstring grouptype =bfromcstr("grouptype"):

3 hid_t object_id;

4 if(!GS_GetStringAttribute(object_id,grouptype,group_type)){

5 bassigncstr(group_type,"...unknown...");

6 }// endif

7 bdestroy(grouptype);

8 ...use group_type...

9 bdestroy(group_type);

hid_t GS_GetValidFileID ( hid_t id )

GS_GetValidFileID returns a valid FileID that contains the object.

Parameters

[in] id An id for an object in a GeoSci file.

Returns: A valid FileID is returned or a value less than 0 on error.

Example: Assume one has opened a file and an image, passes the image_id into a function, and needs the file_id asociated with the image_id.
1 hid_t image_id, file_id;

2 file_id = GS_GetValidFileID(image_id);

3 if(file_id < 0) {

4 printf("Could not get valid file_id\n");

5 }

Details

This function either returns an id that is the same as the passed-in id, but with an incremented reference-count, or it returns a different id, also with an incremented reference-count. The user should always GS_FileClose() this id when done with it. The associated file will only be closed when the reference count reaches zero.

A typical usage of this is to make sure a passed-in id is a file_id. In such a case, this will increment the reference count by 1, and the user should then GS_FileClose() it when done, which will NOT close the file that the passed-in file_id refers to.

In another scenario, where the code needs to return a newly-opened object in the passed-in file_id, one needs to be more careful. Do not use this routine. Instead call GS_ObjectIsFile(id) to make sure the id refers to a file, and return an error if it doesn't.

int GS_GroupClose ( hid_t id )

GS_GroupClose closes a group in a GeoSci Datafile.

See also: GS_GroupOpen()

Parameters

[in] id The handle for the already-open group.

Returns: TRUE is returned if the group is succesfully closed, FALSE otherwise.

Example: Close the file metadata group after opening it:
1 hid_t file_id, meta_id;

2 bstring headername = bfromcstr("/_Header");

3 meta_id = GS_GroupOpen(file_id, headername);

4 bdestroy(headername);

5 if(meta_id < 0) {

6 printf("Failed to open group.\n");

7 return;

8 }

9 ... use it here ...

10 GS_GroupClose(meta_id);

int GS_GroupCloseAllObjects ( hid_t id )

GS_GroupCloseAllObjects closes all open objects in a group.

See also: GS_GroupClose(), GS_FileOpen()

Parameters

[in] id The handle of the open group.

Returns: TRUE is returned on success, FALSE otherwise.

Example: Close all objects in an already-open group:
1 hid_t group_id;

2 if(GS_GroupCloseAllObjects( group_id )){

3 printf("success.\n");

4 } else {

5 printf("failure.\n");

6 }

hid_t GS_GroupCopy	(	hid_t	source,
		hid_t	destination_object_id,
		const_bstring	destination_group_name
	)

GS_GroupCopy copies a group to another location.

See also: GS_GroupClose(), GS_GroupOpen()

Parameters

[in]	source	A handle for a group.
[in]	destination_object_id	The handle of the destination group or file.
[in]	destination_group_name	The name of the new dataset to create.

Returns: The handle of the new group is returned. If it is less than zero, the copy failed.

Example: Copy an image to a new file, call the new image "/Boston_day3". We have already opened the destination file.
1 hid_t source_image_id;

2 hid_t destination_file_id;

3 hid_t group_id;

4 bstring newname = bfromcstr("/Boston_day3");

5 group_id = GS_GroupCopy(source_image_id, destination_file_id, newname);

6 if(group_id < 0) {

7 printf("Failed to copy group.\n");

8 }

9 bdestroy(newname);

hid_t GS_GroupCreate	(	hid_t	file_id,
		const_bstring	groupname
	)

GS_GroupCreate creates a new group in a GeoSci Datafile.

See also: GS_FileOpen(), GS_GroupDelete()

Parameters

[in]	file_id	A handle for an already-open GeoSci datafile.
[in]	groupname	The name of the group in an existing GeoSci datafile to be created. Use Unix/Web filenaming conventions, giving the full pathname, starting with "/". All but the last component of this name must already exist.

Returns

A valid handle to the new group is returned on success. A negative value is returned on failure.

Example: Create a group named "/group3" in an already-open GeoSci file.
1 hid_t file_id, group_id;

2 bstring groupname = bfromcstr("/group3");

3 group_id = GS_GroupCreate(file_id,groupname);

4 bdestroy(groupname);

5 if(group_id < 0 ){

6 printf("GS_GroupCreate failure\n");

7 return;

8 }

9 .... use it here ....

10 GS_GroupClose(group_id);

int GS_GroupDelete	(	hid_t	file_id,
		const_bstring	group_name
	)

GS_GroupDelete deletes a group in a GeoSci datafile.

Parameters

[in]	file_id	A handle for the already-open GeoSci file.
[in]	group_name	The name of the group, starting with a '/' and giving the full path to the group.

Returns: TRUE is returned if the group and all objects it contains are successfully deleted, FALSE otherwise.

Example: Delete an image group named Image1 (should normally call GS_ImageDelete()):
1 hid_t file_id;

2 bstring imagename=bfromcstr("/Image1");

3 if(!GS_GroupDelete(file_id, imagename)){

4 printf("Failed to delete group\n");

5 }

6 bdestroy(imagename);

Details: Deletes the group and all objects it contains.

int GS_GroupGetBounds	(	hid_t	group_id,
		double *	xmin,
		double *	xmax,
		double *	ymin,
		double *	ymax
	)

GS_GroupGetBounds returns the rectangular bounding coordinates.

See also: GS_GroupClose(), GS_GroupOpen(), GS_GroupGetProjection()

Parameters

[in]	group_id	A handle for a group.
[out]	xmin
[out]	xmax
[out]	ymin
[out]	ymax	The coordinates are returned with units that are consistent with the projection that is used. Typically the units are decimal degrees or meters.

Returns: TRUE on success, FALSE if there are any errors.

Example: Print the bounds for a particular group:
1 hid_t group_id;

2 double xmin, xmax, ymin, ymax;

3 if(GS_GroupGetBounds(group_id, &xmin, &xmax, &ymin, &ymax)){

4 printf("X-range: %lf to %lf, Y-range: %lf to %lf\n", xmin,xmax, ymin,ymax);

5 } else {

6 printf("no bounds\n");

7 }

Details: This routine looks at the "bounds" metadata string in order to determine the bounds that go with the data in this group. If this metadata does not exist, or there is an error in obtaining it or parsing it, FALSE is returned. Otherwise, the correct numbers are filled in, and TRUE is returned.

bstring GS_GroupGetDatum ( hid_t group_id )

GS_GroupGetDatum returns a description of the relevant datum if one exists.

See also: GS_GroupClose(), GS_GroupOpen()

Parameters

[in] group_id A handle for a group.

Returns: A string describing the datum that is used for the data in this group. "No Datum" is returned if the datum cannot be determined, or on any other error. This string should be bdestroy()'d when finished with it.

Example: Print the datum for a particular group:
1 hid_t group_id;

2 bstring datum;

3 datum = GS_GroupGetDatum(group_id);

4 printf("%s\n",datum);

5 bdestroy(datum);

Details: This routine looks at the "spatialref" metadata string in order to determine the datum that is being used. If the spatialref metadata item does not exist, then "No Datum" is returned. If the spatialref metadata item exists, then the routine looks for the keyword "DATUM" which should appear in the WKT portion of this metadata. If it is not found, then "No Datum" is returned, otherwise the string that follows this keyword is returned.

bstring GS_GroupGetProjection ( hid_t group_id )

GS_GroupGetProjection returns a description of the relevant projection.

See also: GS_GroupClose(), GS_GroupOpen()

Parameters

[in] group_id A handle for a group.

Returns: A string describing the projection that is used for the data in this group. "No Projection" is returned if the projection cannot be determined, or on any other error. This string should be bdestroy()'d when finished with it.

Example: Print the projection for a particular group:
1 hid_t group_id;

2 bstring projection;

3 projection = GS_GroupGetProjection(group_id);

4 printf("%s\n",projection);

5 bdestroy(projection);

Details: This routine looks at the "spatialref" metadata string in order to determine the projection that is being used. If the spatialref metadata item does not exist, then "No Projection" is returned. If the spatialref metadata item exists, then the routine looks for the keyword "PROJCS" which should appear in the WKT portion of this metadata. If it is found, the string that follows this keyword is returned. If it is not found, then the routine looks for the keyword "GEOGCS" which should appear in the WKT portion of this metadata. If it is found, then the string "Geographic" is returned, otherwise the string "No Projection" is returned.

int GS_GroupGetType ( hid_t group_id )

GS_GroupGetType returns the type of a group in a GeoSci datafile.

See also: GS_GroupOpen()

Parameters

[in] group_id A handle for the group.

Returns

The dataset type code is returned on success:
GS_OBJECT_TYPE_METADATA_GROUP 1
GS_OBJECT_TYPE_IMAGE 2
GS_OBJECT_TYPE_VECTOR 3
GS_OBJECT_TYPE_VECTOR2D 4
GS_OBJECT_TYPE_VECTOR3D 5
GS_OBJECT_TYPE_TIN 6
GS_OBJECT_TYPE_MESH2D 7
GS_OBJECT_TYPE_MESH3D 8
GS_OBJECT_TYPE_RASTER 9
GS_OBJECT_TYPE_IFILE 10
GS_OBJECT_TYPE_METADATA_DATASET 12
GS_OBJECT_TYPE_METADATA_IFILE 13
On failure, the following type code is returned:

GS_OBJECT_TYPE_UNKNOWN

Example: Get the type of an image:
1 hid_t image_id;

2 if(GS_GroupGetType(image_id) != GS_OBJECT_TYPE_IMAGE ) {

3 printf("Dataset is not an image, as expected.\n");

4 }

int GS_GroupIsWriteable	(	hid_t	file_id,
		const_bstring	group_name
	)

GS_GroupIsWriteable returns if the group is writeable or not.

See also: GS_GroupOpen(), GS_GroupClose()

Parameters

[in]	id	A handle for the file.
[in]	group_name	The name of the group in the file. Should start with a "/".

Returns: TRUE if the dataset is writeable, FALSE otherwise.

Example: Determine if a image dataset named "Image1" is writeable or not:
1 hid_t file_id;

2 bstring name = bfromcstr("/Image1");

3 if(GS_GroupIsWriteable(file_id, name)) {

4 printf("It is writeable\n");

5 } else {

6 printf("It is not writeable\n");

7 }

8 bdestroy(name);

int GS_GroupIsWriteableByID ( hid_t group_id )

GS_GroupIsWriteableByID returns if the group is writeable or not.

See also: GS_GroupOpen(), GS_GroupClose()

Parameters

[in] id A handle for the group.

Returns: TRUE if the dataset is writeable, FALSE otherwise.

Example: Determine if a image is writeable or not:
1 hid_t image_id;

2 if(GS_GroupIsWriteableByID(image_id)) {

3 printf("It is writeable\n");

4 } else {

5 printf("It is not writeable\n");

6 }

hid_t GS_GroupOpen	(	hid_t	source,
		const_bstring	name
	)

GS_GroupOpen opens an existing group in a GeoSci datafile.

Parameters

[in]	source	A handle for a file or other container that has a group in it.
[in]	name	The name of the group to open.

Returns: The handle of the opened group is returned. If less than zero, the open failed.

Example: Open the file metadata group:
1 hid_t file_id, meta_id;

2 meta_id = GS_GroupOpen(file_id, bsstatic("_Header"));

3 if(meta_id < 0) {

4 printf("Failed to open group.\n");

5 }

int GS_GroupRename	(	hid_t	id,
		const_bstring	oldname,
		const_bstring	newname
	)

GS_GroupRename renames a group in a GeoSci datafile.

Parameters

[in]	id	A handle for the file, or other container of the group.
[in]	oldname	Current name of group to rename.
[in]	newname	Desired new name of the group.

Returns: TRUE on sucess, FALSE on failure.

Example: Rename an image from "/SIRC-1" to "/SIRC-1a".
1 hid_t file_id;

2 bstring oldname = bfromcstr("/SIRC-1");

3 bstring newname = bfromcstr("/SIRC-1a");

4 if(!GS_GS_GroupRename(file_id, oldname, newname) ) {

5 printf("Failed to rename the group.\n");

6 }

7 bdestroy(oldname);

8 bdestroy(newname);

bstring GS_GroupReport ( hid_t group_id )

GS_GroupReport returns a one-line brief description of the group.

See also: GS_GroupClose(), GS_GroupOpen()

Parameters

[in] group_id A handle for a group.

Returns: A string that provides a brief overview of the group. The string is zero-length on any error. Always bdestroy() the string when done with it.

Example: Get a report string on an image.
1 hid_t raster_id;

2 bstring the_report;

3 the_report = GS_GroupReport(raster_id);

4 printf("Report for the dataset: %s\n",bdata(the_report));

5 bdestroy(the_report);

Details: For Metadata Groups, we use the following string:
1 [Metadata][RW] name: descriptor; last-update-datetime

For Image Groups, we use the following string:
1 [Image][RW] name: descriptor; last-update-datetime

For Vector Groups, we use the following string:
1 [Vector][RW] name: descriptor; last-update-datetime

2 Datum, Projection, Upper-left Lat/long, Lower-right Lat/Long

Where "RW" stands for a group that is both Readable and Writeable, while "RO" would be used for a group that is Read-only. Other Group-types have yet to be defined.

int GS_GroupSetType	(	hid_t	group_id,
		int	typecode
	)

GS_GroupSetType sets the type of a group in a GeoSci datafile.

See also: GS_GroupOpen()

Parameters

[in]	group_id	A handle for the group.
[in]	typecode	An integer type code specifying the type of dataset. One of: `GS_OBJECT_TYPE_METADATA_GROUP` 1 `GS_OBJECT_TYPE_IMAGE` 2 `GS_OBJECT_TYPE_VECTOR` 3 `GS_OBJECT_TYPE_VECTOR2D` 4 `GS_OBJECT_TYPE_VECTOR3D` 5 `GS_OBJECT_TYPE_TIN` 6 `GS_OBJECT_TYPE_MESH2D` 7 `GS_OBJECT_TYPE_MESH3D` 8 `GS_OBJECT_TYPE_RASTER` 9 `GS_OBJECT_TYPE_IFILE` 10 `GS_OBJECT_TYPE_METADATA_DATASET` 12 `GS_OBJECT_TYPE_METADATA_IFILE` 13

Returns: TRUE on sucess, FALSE on failure.

Example: Set the type of an image:
1 hid_t image_id;

2 if(!GS_GroupSetType(image_id, GS_OBJECT_TYPE_IMAGE) ) {

3 printf("Failed to set the type of the image.\n");

4 }

bstring GS_GSObjectTypeAsString ( int objtype )

GS_GSObjectTypeAsString returns printable version of the object type.

Parameters

[in] object_type Object type. One of:
GS_OBJECT_TYPE_METADATA_GROUP 1
GS_OBJECT_TYPE_IMAGE 2
GS_OBJECT_TYPE_VECTOR 3
GS_OBJECT_TYPE_VECTOR2D 4
GS_OBJECT_TYPE_VECTOR3D 5
GS_OBJECT_TYPE_TIN 6
GS_OBJECT_TYPE_MESH2D 7
GS_OBJECT_TYPE_MESH3D 8
GS_OBJECT_TYPE_RASTER 9
GS_OBJECT_TYPE_IFILE 10
GS_OBJECT_TYPE_FILE 11
GS_OBJECT_TYPE_METADATA_DATASET 12
GS_OBJECT_TYPE_METADATA_IFILE 13

Returns

On success, the routine returns the string representation of the object_type according to the following table:

object type	returned string
GS_OBJECT_TYPE_METADATA_GROUP	Metadata
GS_OBJECT_TYPE_IMAGE	Image
GS_OBJECT_TYPE_VECTOR	Vector
GS_OBJECT_TYPE_VECTOR2D	Vector2D
GS_OBJECT_TYPE_VECTOR3D	Vector3D
GS_OBJECT_TYPE_TIN	TIN
GS_OBJECT_TYPE_MESH2D	Mesh2D
GS_OBJECT_TYPE_MESH3D	Mesh3D
GS_OBJECT_TYPE_RASTER	Raster
GS_OBJECT_TYPE_IFILE	Internal File
GS_OBJECT_TYPE_FILE	File
GS_OBJECT_TYPE_METADATA_DATASET	Metadata Dataset
GS_OBJECT_TYPE_METADATA_IFILE	Metadata Internal File

On failure, the string "Unknown Object Type" is returned.

Note that the returned string should NOT be GFree'd or bdestroy'd when done.

Example: Obtain list of objects in a file named "testimage.hd5".
1 ...

2 bstring *objnames;

3 int objtypes;

4 int nobjs;

5 int i;

6

7 file_id = GS_FileOpen("testimage.hd5","r+");

8 if(file_id<0){

9 printf("GS_FileOpen failed\n");

10 printf("%s\n",bdata(error_string));

11 exit(-1);

12 }//endif

13

14 if(!GS_ObjectGetGSChildren(file_id, &nobjs, &objnames,&objtypes)){

15 printf("GS_ObjectGetGSChildren failed\n");

16 printf("%s\n",bdata(error_string));

17 exit(-1);

18 }

19

20 // print results:

21 for(i=0;i<nobjs;i++){

22 printf("obj# %d: %s (%s)\n",i,bdata(objnames[i]),

23 bdata(GS_GSObjectTypeAsString(objtypes[i])));

24 }

25

26 // clean up:

27 for(i=0;i<nobjs;i++){

28 bdestroy(objnames[i]);

29 }

30 GFree(objnames);

31 GFree(objtypes);

bstring GS_H5ObjectTypeAsString ( int objtype )

GS_H5ObjectTypeAsString returns a printable version of HDF5 object type.

Parameters

[in] object_type object type, as an integer. One of:
H5O_TYPE_GROUP
H5O_TYPE_DATASET
H5O_TYPE_NAMED_DATATYPE

Returns: On success, the routine returns the string representation of the object type according to the following table:

object type	returned string
H5O_TYPE_GROUP	Group
H5O_TYPE_DATASET	Dataset
H5O_TYPE_NAMED_DATATYPE	Named Datatype

On failure, the string "Unknown Object Type" is returned.

Note that the returned string should NOT be bdestroy'd when done.

Example: Obtain list of objects in a file named "testimage.hd5".
1 ...

2 char **objnames;

3 int objhdftypes;

4 int nobjs;

5 int i;

6

7 file_id = GS_FileOpen(bsstatic("testimage.hd5"),bsstatic("r+"));

8 if(file_id<0){

9 printf("GS_FileOpen failed\n");

10 printf("%s\n",bdata(error_string));

11 exit(-1);

12 }//endif

13

14 if(!GS_ObjectGetH5Children(file_id, &nobjs, &objnames,&objhdftypes)){

15 printf("GS_ObjectGetH5Children failed\n");

16 printf("%s\n",bdata(error_string));

17 exit(-1);

18 }

19

20 // print results:

21 for(i=0;i<nobjs;i++){

22 printf("obj# %d: %s (%s)\n",i,bdata(objnames[i]),

23 GS_H5ObjectTypeAsString(objhdftypes[i]));

24 }

25

26 // clean up:

27 for(i=0;i<nobjs;i++){

28 bdestroy(objnames[i]);

29 }

30 GFree(objnames);

31 GFree(objhdftypes);

int GS_HDFDatatypeClose ( hid_t id )

GS_HDFDatatypeClose closes an HDF datatype.

See also: GS_ConvertToHDFDatatype()

Parameters

[in] id The id of the datatype.

Returns: TRUE on success, ERROR (-1) on failure.

Example: After opening a datatype using GS_ConvertToHDFDatatype(), close it:
1 hid_t hdf_type;

2 hdf_type = GS_ConvertToHDFDatatype(GS_DATATYPE_R64);

3 if(hdf_type<0){

4 printf("GS_ConvertToHDFDatatype failed\n");

5 return;

6 }

7 if(!GS_HDFDatatypeClose(hdf_type)){

8 printf("failed to close the datatype\n");

9 }

Details: This function is not needed for most types, as they are not really opened to begin with. However, the complex datatypes are opened, and so need to be closed.

int GS_ImageClose ( hid_t image_id )

GS_ImageClose closes an Open Image}.

See also: GS_ImageOpen(), GS_FileOpen(), GS_ImageCreate()

Parameters

[in] image_id Image handle of an image in a GEOSCI file.

Returns: Returns TRUE on success, FALSE on failure.

Example: Close an image.
1 ...

2 hid_t image_id;

3

4 if(!GS_ImageClose(image_id)){

5 printf("GS_ImageClose failed.\n");

6 return;

7 }

8 ...

hid_t GS_ImageCreate	(	hid_t	file_id,
		const_bstring	image_name,
		const_bstring	image_descriptor
	)

GS_ImageCreate creates a new image in a GeoSci file and opens it.

See also: GS_FileCreate, GS_RasterCreate

Parameters

[in]	file_id
[in]	imagename	Name of the image to create. Must not be the same as any other existing object in the file or the creation will fail.
[in]	image_descriptor	A string describing the contents of the image. This describes all the channels, in a general sense.

Returns: Returns an image handle on success, or a negative integer on failure.

Example: Create an image named "sirc-102.41-spring" with an image descriptor of "raw slc data".
1 ...

2 hid_t file_id;

3 bstring name = bfromcstr("sirc-102.41-spring");

4 bstring descriptor = bfromcstr("raw slc data");

5

6 image_id = GS_ImageCreate(file_id, name, descriptor)

7 if(image_id < 0) {

8 printf("image creation failed.\n");

9 }// endif

10 bdestroy(name);

11 bdestroy(descriptor);

12 ...

int GS_ImageCreateMetadata	(	hid_t	file_id,
		const_bstring	image_name,
		const_bstring	descriptor
	)

GS_ImageCreateMetadata fills the standard image metadata attributes with the values that are passed in.

See also: GS_ImageCreate()

Parameters

[in]	file_id	The file ID
[in]	image_name	A character string giving the name of the image.
[in]	descriptor	A character string describing the image contents.

Returns: TRUE on success, FALSE on failure.

Example:

After creating a new image named "datatake 34" in a file named "av1.h5", we must set the metadata for the image before the image object can be used. The descriptor is "Apr 3, 2012, 2:18 PM".

 hid_t file_id;
 bstring filename=bfromcstr("av1.h5");
 bstring access=bfromcstr("r+");
 file_id = GS_FileOpen(filename,access);
 bdestroy(filename);
 bdestroy(access);
 if(file_id > 0) {
    ... create a group with datasets in it that represent the image...
    bstring name = bfromcstr("datatake 34");
    bstring descriptor = bfromcstr("Apr 3, 2012, 2:18 PM");
    if(GS_ImageCreateMetadata(file_id,name,descriptor){
       printf("success\n");
    }
    bdestroy(name);
    bdestroy(descriptor);
 }

Details:

The image metadata is attached to the Group within which all the Datasets are stored. The image metadata items are: grouptype (= "Image"), descriptor, creation_datetime, last_update_datetime, history, and writeable.

Note that until the image metadata is set up correctly the image is not recognized as a valid GeoSci Image object, and so most functions in this library will not operate on it successfully. Because of this, the image creation functions, such as GS_ImageCreate, call this function as part of the creation process.

int GS_ImageDelete	(	hid_t	file_id,
		const_bstring	image_name
	)

GS_ImageDelete deletes an existing image.

See also: GS_ImageOpen(), GS_FileOpen(), GS_FileCreate()

Parameters

[in]	file_id;	File handle of selected GeoSci file
[in]	image_name	Name of image to delete.

Returns: TRUE is returned on success, FALSE on failure.

Example: Delete an image named "/Channel_1" in a file named "test123.h5".
1 ...

2 hid_t file_id;

3 bstring name = bfromcstr("test123.h5");

4 bstring access = bfromcstr("r+");

5 file_id = GS_FileOpen(name,access);

6 bdestroy(name);

7 bdestroy(access);

8 if(file_id < 0) {

9 printf("Could not open file.\n");

10 return;

11 }

12 bstring image_name = bfromcstr("/Channel_1");

13 if(!GS_ImageDelete(file_id,image_name)){

14 printf("image deletion failed.\n");

15 bdestroy(image_name);

16 return;

17 }

18 bdestroy(image_name);

19 ...

hid_t GS_ImageOpen	(	hid_t	file_id,
		const_bstring	image_name
	)

GS_ImageOpen opens an existing image.

See also: GS_FileOpen(), GS_ImageCreate(), GS_ImageClose()

Parameters

[in]	file_id	File handle of selected GeoSci file.
[in]	image_name	Name of image to open.

Returns: A handle to the image is returned on success, while a value less than 0 is returned on failure.

Example: Open an image named "Channel_1" in a file named "test123.h5".
1 ...

2 hid_t file_id, image_id;

3 bstring name = bfromcstr("test123.h5");

4 bstring access = bfromcstr("r+");

5 file_id = GS_FileOpen(name, access);

6 bdestroy(name);

7 bdestroy(access);

8 if(file_id < 0) {

9 printf("Could not open file.\n");

10 return;

11 }

12 bstring image_name = bfromcstr("/Channel_1");

13 image_id = GS_ImageOpen(file_id,image_name);

14 bdestroy(image_name);

15 if(image_id < 0) {

16 printf("Could not open image.\n");

17 return;

18 }

19 ...

void GS_init ( )

GS_init initialize some global strings.

Example: Before the first use of any GS_* function call this first:
1 ...

2

3 GS_init();

4

5 ... call GS_* functions here...

Details: This function must be called once, before any other GeoSci functions in order to initialize some important things.

int GS_ObjectGetGSChildren	(	hid_t	object_id,
		int *	nobjs,
		bstring **	objnames,
		int **	objtypes
	)

GS_ObjectGetGSChildren returns list of GeoSci children objects.

Parameters

[in]	object_id	handle of an open object. The names of the children of this object, if any, are returned.
[out]	nobjs	The number of objects (children) found.
[out]	objnames	The returned list of object names. when done, bdestroy() each element, and GFree the container.
[out]	objtypes	The returned list of object types. GFree it when done. Valid values are: GS_OBJECT_TYPE_METADATA_GROUP 1 GS_OBJECT_TYPE_IMAGE 2 GS_OBJECT_TYPE_VECTOR 3 GS_OBJECT_TYPE_VECTOR2D 4 GS_OBJECT_TYPE_VECTOR3D 5 GS_OBJECT_TYPE_TIN 6 GS_OBJECT_TYPE_MESH2D 7 GS_OBJECT_TYPE_MESH3D 8

Returns: The routine returns TRUE on success, FALSE on failure.

Example: Obtain list of objects in a file named "testimage.hd5".
1 ...

2 bstring *objnames;

3 int objtypes;

4 int nobjs;

5 int i;

6

7 file_id = GS_FileOpen(bsstatic("testimage.hd5"),bsstatic("r+"));

8 if(file_id<0){

9 printf("GS_FileOpen failed\n");

10 printf("%s\n",bdata(error_string));

11 exit(-1);

12 }//endif

13

14 if(!GS_ObjectGetGSChildren(file_id, &nobjs, &objnames,&objtypes)){

15 printf("GS_ObjectGetGSChildren failed\n");

16 printf("%s\n",bdata(error_string));

17 exit(-1);

18 }

19

20 // print results:

21 for(i=0;i<nobjs;i++){

22 printf("obj# %d: %s (%s)\n",i,bdata(objnames[i]),

23 bdata(GS_GSObjectTypeAsString(objtypes[i])) );

24 }

25

26 // clean up:

27 for(i=0;i<nobjs;i++){

28 bdestroy(objnames[i]);

29 }

30 GFree(objnames);

31 GFree(objtypes);

int GS_ObjectGetH5Children	(	hid_t	object_id,
		int *	nobjs,
		bstring **	objnames,
		int **	objtypes
	)

GS_ObjectGetH5Children returns list of all children objects.

See also: GS_ObjectGetGSChildren()

Parameters

[in]	object_id	Handle of an open object. The names of the children of this object, if any, are returned.
[out]	nobjs;	The number of objects (children) returned.
[out]	objnames;	The returned list of object names. bdestroy() each item it when done, and GFree() entire list when done.
[out]	objtypes;	The returned list of object types. GFree it when done. Valid values are: H5O_TYPE_GROUP H5O_TYPE_DATASET H5O_TYPE_NAMED_DATATYPE

Returns: TRUE on success FALSE on failure.

Example: Obtain list of objects in a file named "testimage.hd5".

     ...
 bstring *objnames;
 int objhdftypes;
 int nobjs;
 int i;
 bstring filename = bfromcstr("testimage.hd5");
 bstring access = bfromcstr("r+");
 file_id = GS_FileOpen(filename,access);
 bdestroy(filename);
 bdestroy(access);
 if(file_id<0){
    printf("GS_FileOpen failed\n");
    printf("%s\n",error_string);
    exit(-1);
 }//endif
 
 if(!GS_ObjectGetH5Children(file_id, &nobjs, &objnames,&objhdftypes)){
    printf("GS_ObjectGetH5Children failed\n");
    printf("%s\n",error_string);
    exit(-1);
 }
 
 // print results:
 for(i=0;i<nobjs;i++){
    printf("obj# %d: %s (%s)\n",i,objnames[i],
            GS_H5ObjectTypeAsString(objhdftypes[i]));
 }
 
 // clean up:
 for(i=0;i<nobjs;i++){
    bdestroy(objnames[i]);
 }
 GFree(objnames);
 GFree(objhdftypes);

int GS_ObjectIsDataset	(	hid_t	id,
		const_bstring	name
	)

GS_ObjectIsDataset determines if an object is a dataset.

See also: GS_FileOpen(), GS_FileCreate()

Parameters

[in]	id	File handle or Image handle of selected GeoSci file.
[in]	object_name;	Name of object to query.

Returns: TRUE is returned if the object is a dataset, FALSE otherwise.

Example:: Query about a raster named "r1" in an image named "Channel_1", in a file named "test123.h5".
1 hid_t file_id, image_id;

2 bstring filename = bfromcstr("test123.h5");

3 bstring access = bfromcstr("r+");

4 file_id = GS_FileOpen(filename,access);

5 if(file_id < 0) {

6 printf("Could not open file.\n");

7 bdestroy(filename);

8 bdestroy(access);

9 return;

10 }

11 bdestroy(filename);

12 bdestroy(access);

13 bstring channel=bfromcstr("Channel_1");

14 image_id = GS_ImageOpen(file_id,channel);

15 if(image_id < 0) {

16 printf("Could not open image.\n");

17 bdestroy(channel);

18 return;

19 }

20 bdestroy(channel);

21 bstring dataset_name = bfromcstr("r1");

22 if(GS_ObjectIsDataset(image_id,dataset_name)){

23 ... open the object as a dataset and do stuff ....

24 } else {

25 printf("Object is not a dataset.\n");

26 } // endif

27 bdestroy(dataset_name);

int GS_ObjectIsDatasetByID ( hid_t id )

GS_ObjectIsDatasetByID determines if an object-id refers to a dataset.

See also: GS_FileOpen(), GS_FileCreate()

Parameters

[in] id object handle in selected GeoSci file.

Returns: TRUE is returned if the object is a dataset, FALSE otherwise.

Example:: Query about a raster that was already opened:
1 hid_t raster_id;

2 if(GS_ObjectIsDatasetByID(raster_id)){

3 ... the object is a dataset: use it...

4 } else {

5 printf("Object is not a dataset.\n");

6 } // endif

int GS_ObjectIsFile ( hid_t id )

GS_ObjectIsFile determines if an object-id refers to a file.

See also: GS_FileOpen(), GS_FileCreate()

Parameters

[in] id Object handle of selected GeoSci file.

Returns: TRUE is returned if the object is a file, FALSE otherwise.

Example:: Query about an image that was already opened:
1 C hid_t image_id;

2 C if(GS_ObjectIsFile(image_id)){

3 C ... the object is a file: use it...

4 C } else {

5 C printf("Object is not a file.\n");

6 C } // endif

int GS_ObjectIsGroup	(	hid_t	id,
		const_bstring	name
	)

GS_ObjectIsGroup determines if a named object is a group.

See also: GS_FileOpen(), GS_FileCreate()

Parameters

[in]	id	object handle of a file or another group in the selected GeoSci datafile.
[in]	object_name	Name of object to query. This name is relative to the given object.

Returns: TRUE is returned if the object is a group, FALSE otherwise.

Example:: Query about an image named "Channel_1" in a file named "test123.h5".
1 hid_t file_id;

2 bstring filename = bfromcstr("test123.h5");

3 bstring access = bfromcstr("r+");

4 file_id = GS_FileOpen(filename,access);

5 if(file_id < 0) {

6 printf("Could not open file.\n");

7 bdestroy(filename);

8 bdestroy(access);

9 return;

10 }

11 bstring channel = bfromcstr("Channel_1");

12 if(GS_ObjectIsGroup(file_id,channel)){

13 ... open the object as a group and use it ....

14 } else {

15 printf("Object is not a group.\n");

16 } // endif

17 bdestroy(channel);

int GS_ObjectIsGroupByID ( hid_t id )

GS_ObjectIsGroupByID determines if an object-id refers to a group.

See also: GS_FileOpen(), GS_FileCreate()

Parameters

[in] object_id object handle in a GeoSci file.

Returns: TRUE is returned if the object is a group, FALSE otherwise.

Example:: Query about an image named "Channel_1" in a file named "test123.h5".
1 hid_t file_id, image_id;

2 bstring filename = bfromcstr("test123.h5");

3 bstring access = bfromcstr("r+");

4 file_id = GS_FileOpen(filename,access);

5 if(file_id < 0) {

6 printf("Could not open file.\n");

7 bdestroy(filename);

8 bdestroy(access);

9 return;

10 }

11 bdestroy(filename);

12 bdestroy(access);

13 bstring channel = bfromcstr("Channel_1");

14 image_id = GS_ImageOpen(file_id,channel);

15 if(image_id < 0) {

16 printf("Could not open image.\n");

17 bdestroy(channel);

18 return;

19 }

20 bdestroy(channel);

21 if(GS_ObjectIsGroupByID(image_id)){

22 ... open the object as a group and use it ....

23 } else {

24 printf("Object is not a group.\n");

25 } // endif

int GS_ObjectIsIFile	(	hid_t	id,
		const_bstring	name
	)

GS_ObjectIsIFile determines if the object is an internal file.

Parameters

[in]	id	The handle for the already-open group.
[in]	name	The name of the ifile within the group.

Returns: TRUE is returned if the object is an IFile, FALSE otherwise.

Example: Open an internal file and query if it's valid IFile handle:
1 hid_t file_id;

2 hid_t group_id;

3

4 group_id = GS_GroupOpen(file_id,"/somename");

5 if(group_id < 0) {

6 printf("GS_GroupOpen failed on /somename\n");

7 }

8 bstring internal_file_name=bfromcstr("internal_file_name");

9 if(!GS_ObjectIsIFile(group_id, internal_file_name )){

10 printf("Object is not an internal file.\n");

11 }

12 bdestroy(internal_file_name);

int GS_ObjectIsIFileByID ( hid_t dataset_id )

GS_ObjectIsIFileByID determines if the objectID is an internal file.

Parameters

[in] id The handle of the open internal file.

Returns: TRUE is returned if the object is an IFile, FALSE otherwise.

Example: Open an internal file and query if it's valid IFile handle:
1 hid_t file_id;

2 hid_t internal_file_id;

3

4 internal_file_id = GS_IFileOpen(file_id,"/somename","w");

5 if(internal_file_id < 0) {

6 printf("GS_IFileOpen failed on /somename\n");

7 }

8

9 if(!GS_ObjectIsIFileByID(internal_file_id)){

10 printf("Object is not an internal file.\n");

11 }

int GS_ObjectIsImage	(	hid_t	file_id,
		const_bstring	image_name
	)

GS_ObjectIsImage determines if the object is an image.

See also: GS_ImageCreate(), GS_ImageOpen()

Parameters

[in]	id	The handle of an object in a GeoSci file.
[in]	object_name;	Name of object to query. This name is relative to the given object.

Returns: TRUE on success, FALSE on failure.

Example:: Query if an object is a valid image.
1 bstring filename = bfromcstr("/somename");

2 if(!GS_ObjectIsImage(file_id,filename);

3 printf("Object is not an image.\n");

4 }

5 bdestroy(filename);

int GS_ObjectIsImageByID ( hid_t id )

GS_ObjectIsImageByID determines if the object is an image.

See also: GS_ImageCreate(), GS_ImageOpen()

Parameters

[in] id; The handle of the open objbect.

Returns: TRUE on success, FALSE on failure.

Example:: Query if an object is a valid image.
1 hid_t file_id;

2 hid_t image1;

3 bstring filename = bfromcstr("/somename");

4 image1 = GS_ImageOpen(file_id,filename);

5 bdestroy(filename);

6 if(image1 < 0) {

7 printf("GS_ImageOpen failed on /somename\n");

8 }

9 if(!GS_ObjectIsImageByID(image1)){

10 printf("Object is not an image.\n");

11 }

int GS_ObjectIsMetadataDataset	(	hid_t	id,
		const_bstring	name
	)

ObjectIsMetadataDataset determines if the object is a metadata dataset.

See also: IFileOpen, IFileClose

Parameters

[in]	id	The handle of the open group.
[in]	name	The name of the object within the group.

Returns: TRUE is returned if it is, FALSE otherwise.

Example: Open the Location metadata for an image and query if it's valid Metadata Dataset:
1 hid_t file_id;

2 hid_t group_id;

3 bstring name =bfromcstr("/somename");

4 group_id = GS_GroupOpen(file_id,name);

5 bdestroy(name);

6 if(group_id < 0) {

7 printf("GS_GroupOpen failed on /somename\n");

8 }

9 bstring dname = bfromcstr("location");

10 if(!GS_ObjectIsMetadataDataset(group_id, dname)){

11 printf("Object is not a Metadata Dataset.\n");

12 }

13 bdestroy(dname);

int GS_ObjectIsMetadataDatasetByID ( hid_t dataset_id )

ObjectIsMetadataDatasetByID determines if the objectid is a metadata dataset.

See also: IFileOpen, IFileClose

Parameters

[in] id The handle of the open object.

Returns: TRUE is returned if it is, FALSE otherwise.

Example: Open the Location metadata for an image and query if it's a valid Metadata Dataset:
1 hid_t file_id;

2 hid_t objid;

3 bstring name = bfromcstr("/someimage/location");

4 objid = GS_DatasetOpen(file_id,name);

5 if(objid < 0) {

6 printf("GS_DatasetOpen failed on /someimage\n");

7 }

8 bdestroy(name);

9 if(!GS_ObjectIsMetadataDatasetByID(objid)){

10 printf("Object is not a metadata dataset.\n");

11 }

int GS_ObjectIsMetadataIFile	(	hid_t	id,
		const_bstring	name
	)

GS_ObjectIsMetadataIFile determines if the object refers to a metadata internal-file.

See also: GS_ObjectIsMetadataIFileByID(), IFileOpen(), GS_FileClose()

Parameters

[in]	id	The handle of the open group.
[in]	name	The name of the object within the group.

Returns: TRUE on success, FALSE on failure.

Example:: Open the Location metadata for an image and query if it's valid Metadata IFile:
1 hid_t file_id;

2 hid_t group_id;

3 bstring name = bfromcstr("/somename");

4 group_id = GS_GroupOpen(file_id,name);

5 if(group_id < 0) {

6 printf("GS_GroupOpen failed on /somename\n");

7 }

8 bdestroy(name);

9 bstring location = bfromcstr("location");

10 if(!GS_ObjectIsMetadataIFile(group_id, location)){

11 printf("Object is not a Metadata IFile.\n");

12 }

13 bdestroy(location);

Details:: Some Metadata is stored as metadata items assocated with Groups, and other metadata is large enough that we create internal files (IFiles) to store the data in. These files are like ordinary files, except that they are internal to the GeoSci file. They can be binary, or text, and the arrangement of the data within them is specific to the Metadata that needs to be stored. The names of these IFiles are used to determine the format. We have coders and ecoders for each format so that the actual format used does not need to be known by users of the system.

int GS_ObjectIsMetadataIFileByID ( hid_t dataset_id )

GS_ObjectIsMetadataIFileByID determines if the object-id refers to a metadata internal-file.

See also: GS_ObjectIsMetadataIFile(), IFileOpen(), GS_FileClose()

Parameters

[in] id The handle of the open object.

Returns: TRUE on success, FALSE on failure.

Example:: Open the Location metadata for an image and query if it's valid Metadata IFile:
1 hid_t file_id;

2 hid_t objid;

3 bstring name = bfromcstr("someimage/location");

4 objid = GS_DatasetOpen(file_id,name);

5 if(objid < 0) {

6 printf("GS_DatasetOpen failed on /someimage/location\n");

7 }

8 bdestroy(name);

9 if(!GS_ObjectIsMetadataIFileByID(objid)){

10 printf("Object is not a metadata internal file.\n");

11 }

Details:: Some Metadata is stored as metadata items assocated with Groups, and other metadata is large enough that we create internal files (IFiles) to store the data in. These files are like ordinary files, except that they are internal to the GeoSci file. They can be binary, or text, and the arrangement of the data within them is specific to the Metadata that needs to be stored. The names of these IFiles are used to determine the format. We have coders and ecoders for each format so that the actual format used does not need to be known by users of the system.

int GS_ObjectIsRaster	(	hid_t	id,
		const_bstring	name
	)

GS_ObjectIsRaster determines if the object is a raster image.

See also: GS_ObjectIsRasterByID(), IFileOpen(), GS_FileClose()

Parameters

[in]	id	The handle of the open image.
[in]	name	Name of the raster within the image.

Returns: TRUE on success, FALSE on failure.

Example:: Open an image and query if the dataset named "r1" is a valid raster image.
1 hid_t file_id;

2 hid_t image1;

3 bstring name = bfromcstr("/somename");

4 image1 = GS_ImageOpen(file_id,name);

5 if(image1 < 0) {

6 printf("GS_ImageOpen failed on /somename\n");

7 }

8 bdestroy(name);

9 if(!GS_ObjectIsRaster(image1,r1)){

10 printf("Object is not a raster image.\n");

11 }

int GS_ObjectIsRasterByID ( hid_t dataset_id )

GS_ObjectIsRasterByID determines if the object-id refers to a raster image.

See also: GS_ObjectIsRaster(), IFileOpen(), GS_FileClose()

Parameters

[in] id The handle of the open raster.

Returns: TRUE on success, FALSE on failure.

Example:: Open a raster image and query if it's valid raster image
1 hid_t file_id;

2 hid_t raster1;

3 bstring name = bfromcstr("/somename/r1");

4 raster1 = GS_RasterOpen(file_id,name);

5 if(raster1 < 0) {

6 printf("GS_RasterOpen failed on /somename/r1\n");

7 }

8 bdestroy(name);

9 if(!GS_ObjectIsRasterByID(raster1)){

10 printf("Object is not a raster image.\n");

11 }

int GS_ObjectIsVector	(	hid_t	id,
		const_bstring	name
	)

GS_ObjectIsVector determines if the object is a vector.

See also: GS_ObjectIsVectorByID(), IFileOpen(), GS_FileClose()

Parameters

[in]	id	object handle of a file or another group in the selected GeoSci file.
[in]	object_name	Name of object to query. This name is relative to the given object.

Returns: TRUE on success, FALSE on failure.

Example:: Query if an object is a valid vector.
1 bstring name = bfromcstr("/somename");

2 if(!GS_ObjectIsVector(file_id,name)){

3 printf("Object is not a vector.\n");

4 }

int GS_ObjectIsVectorByID ( hid_t id )

GS_ObjectIsVectorByID determines if the object-id refers to a vector.

See also: GS_ObjectIsVector(), IFileOpen(), GS_FileClose()

Parameters

[in] id The handle of the open vector.

Returns: TRUE on success, FALSE on failure.

Example:: Open a vector and query if it is a valid vector.
1 hid_t file_id;

2 hid_t vector1;

3 bstring filename = bfromcstr("/somename");

4 vector1 = GS_VectorOpen(file_id,filename);

5 bdestroy(filename);

6 if(vector1 < 0) {

7 printf("GS_VectorOpen failed on /somename\n");

8 }

9 if(!GS_ObjectIsVectorByID(vector1)){

10 printf("Object is not a vector.\n");

11 }

int GS_ObjectLock ( hid_t id )

GS_ObjectLock makes an object read-only.

See also: GS_ObjectUnlock()

Parameters

[in] id The handle of the file, or any object in the file.

Returns: Returns TRUE if the object is now (or was already) read-only. Returns FALSE if the object is still read/write, or on any error.

Example:: Make an image named "testimage" be read-only.
1 hid_t object_id;

2 bstring name = bfromcstr("testimage");

3 object_id = GS_ImageOpen(file_id,name);

4 if(object_id < 0){

5 printf("Could not open the image.\n");

6 return;

7 }

8 bdestroy(name);

9 if(!GS_ObjectLock(object_id)){

10 printf("Could not make image read-only.\n");

11 return;

12 }

Details:: Yet: fill in details of how different object-types are handled.

int GS_ObjectUnlock ( hid_t id )

GS_ObjectUnlock changes and object to have read-write status.

See also: GS_ObjectLock()

Parameters

[in] id The handle of the file, or any object in the file.

Returns: Returns TRUE if the object is now (or was already) read-write. Returns FALSE if the object is still read-only, or on any error.

Example:: Make an image named "testimage" be read-write.
1 hid_t object_id;

2 bstring name = bfromcstr("testimage");

3 object_id = GS_ImageOpen(file_id,name);

4 if(object_id < 0){

5 printf("Could not open the image.\n");

6 bdestroy(name);

7 return;

8 }

9 bdestroy(name);

10 if(!GS_ObjectUnlock(object_id)){

11 printf("Could not make image read-write.\n");

12 return;

13 }

bstring GS_PathnameGetDir ( const_bstring name )

GS_PathnameGetDir returns the directory name of the pathname.

See also: GS_PathnameJoin()

Parameters

[in] name The pathname to process.

Returns: Returns a bstring of the stripped name, which has zero length if there is any kind of error. bdestroy() it when done.

Example: This example starts with a path of "/some/path/name/here/blah" and the returned value from GS_PathnameGetDir is: "/some/path/name/here".
1 bstring longname=bfromcstr("/some/path/name/here/blah");

2 bstring the_name;

3 the_name = GS_PathnameGetDir(longname);

4 if(bstrlen(the_name)==0){

5 printf("Could not determine the name\n");

6 }

7 printf("The directory name is: %s\n",bdata(the_name));

8 bdestroy(the_name);

9 bdestroy(long_name);

Details: For filenames that have no "/" characters ('\' in windows), a zero-length string is returned. It's not null. It still needs to be bdestroy()'d when you are done with it.

bstring GS_PathnameGetHDFDir ( const_bstring name )

GS_PathnameGetHDFDir returns the directory name of the pathname.

See also: GS_PathnameNoDir(), GS_PathnameJoin()

Parameters

[in] name The pathname to process.

Returns: Returns a bstring of the processed name, which has zero length if there is any kind of error. bdestroy() it when done.

Example: This example starts with a path of "/some/path/name/here/blah" and the returned value from GS_PathnameGetHDFDir is: "/some/path/name/here".
1 bstring longname=bfromcstr("/some/path/name/here/blah");

2 bstring the_name;

3 the_name = GS_PathnameGetHDFDir(longname);

4 if(bstrlen(the_name)==0){

5 printf("Could not determine the name\n");

6 }

7 printf("The directory name is: %s\n",bdata(the_name));

8 bdestroy(the_name);

9 bdestroy(long_name);

Details: Assumes directories are separated with "/". For filenames that have no "/" characters, a zero-length string is returned. It's not null. It still needs to be bdestroy()'d when you are done with it.

bstring GS_PathnameJoin	(	const_bstring	front,
		const_bstring	back
	)

GS_PathnameJoin joins 2 pieces of a pathname.

See also: GS_PathnameGetDir()

Parameters

[in]	front	The front part of the pathname. Should not end with a '/' or a '\'.
[in]	back	The back part of the pathname. Should not start or end end with a '/' or a '\'.

Returns: Returns a bstring of the joined names, which has zero length if there is any kind of error. bdestroy() it when done.

Example: This example starts with a path of "/some/path/name/here/blah" and a relative filename of "trash.dat". The returned value from GS_PathnameJoin (on unix) is: "/some/path/name/here/blah/trash.dat".
1 bstring longname=bfromcstr("/some/path/name/here/blah");

2 bstring ending=bfromcstr("trash.dat");

3 bstring the_name;

4 the_name = GS_PathnameJoin(longname,ending);

5 if(bstrlen(the_name)==0){

6 printf("Could not join the names\n");

7 return;

8 }

9 printf("The joined name is: %s\n",bdata(the_name));

10 bdestroy(the_name);

11 bdestroy(longname);

12 bdestroy(ending);

Details: It uses the correct joining character for the operating system: for LINUX, MACOS: '/', for Windows: '\'.

bstring GS_PathnameNodir ( const_bstring name )

GS_PathnameNoDir strips the directory name from the pathname.

See also: GS_PathnameGetDir(), GS_PathnameJoin()

Parameters

[in] name The pathname to process.

Returns: Returns a bstring of the stripped name, which has zero length if there is any kind of error. bdestroy() it when done.

Example: This example starts with a path of "/some/path/name/here/blah" and the returned value from GS_PathnameNoDir is: "blah".
1 bstring longname=bfromcstr("/some/path/name/here/blah");

2 bstring the_name;

3 the_name = GS_PathnameNoDir(longname);

4 if(bstrlen(the_name)==0){

5 printf("Could not determine the name\n");

6 }

7 printf("The stripped name is: %s\n",bdata(the_name));

8 bdestroy(the_name);

9 bdestroy(long_name);

Details: For filenames that end with a "/" ('\' in windows), a zero-length string is returned. It's not null. It still needs to be bdestroy()'d when you are done with it.

int GS_RasterCheckWindow	(	hid_t	image_id,
		const_bstring	raster_name,
		int *	window
	)

GS_RasterCheckWindow checks whether a requested window selection is within the bounds of an image. It will also default a window specification to be the whole image if XSize and/or YSize are zero.

See also: GS_RasterCheckWindowByID()

Parameters

[in]	image_id	Image handle that has the raster in it.
[in]	raster_name	Name of raster to check.
[in,out]	window	Vector containing desired window specification: window[0] = Xoffset window[1] = Yoffset window[2] = Xsize window[3] = Ysize If window[2] is 0, window[2] will be set to image X size - window[0]. If window[3] is 0, window[3] will be set to image Y size - window[1].

Returns: TRUE is returned on success, FALSE on failure.

Example: In this example a GeoSci raster is opened and a user specified window is checked for validity in one of its images.
1 ...

2 hid_t image_id;

3 int window[4];

4 ...

5 window[0]=0;

6 window[1]=0;

7 window[2]=512;

8 window[3]=1024;

9 if(!GS_RasterCheckWindow( image_id, bsstatic("r1"), window)) {

10 printf("GS_RasterCheckWindow failure.\n");

11 }

12 ...

int GS_RasterCheckWindowByID	(	hid_t	raster_id,
		int *	window
	)

GS_RasterCheckWindowByID checks whether a requested window selection is within the bounds of a raster. It will also default a window specification to be the whole raster if XSize and/or YSize are zero.

See also: GS_RasterCheckWindow

Parameters

[in]	raster_id	Handle of raster to check.
[in,out]	window	Vector containing desired window specification: window[0] = Xoffset window[1] = Yoffset window[2] = Xsize window[3] = Ysize If window[2] is 0, on return window[2] will be set to image X size - window[0]. If window[3] is 0, on return window[3] will be set to image Y size - window[1].

Returns: TRUE is returned on success, FALSE on failure.

Example: In this example a GeoSci file and raster is opened and a user specified window is checked for validity in one of its rasters.
1 ...

2 hid_t file_id, image_id, raster_id;

3 int window[4];

4 ...

5 bstring file = bfromcstr("blah.h5");

6 file_id = GS_FileOpen( file, bsstatic("r+") );

7 if(!file_id) {

8 printf("GS_FileOpen failed.\n");

9 exit(-1);

10 }

11

12 image_id = GS_ImageOpen( file_id, "/image1" );

13 if(!image_id) {

14 printf("GS_ImageOpen failed.\n");

15 exit(-1);

16 }

17

18 raster_id = GS_RasterOpen( file_id, "r5" );

19 if(!raster_id) {

20 printf("GS_RasterOpen failed.\n");

21 exit(-1);

22 }

23

24 window[0]=0;

25 window[1]=0;

26 window[2]=512;

27 window[3]=1024;

28 if(!GS_RasterCheckWindowByID( raster_id, window)) {

29 printf("GS_RasterCheckWindowByID failure.\n");

30 }

31 ...

int GS_RasterClose ( hid_t raster_id )

GS_RasterClose closes an open raster dataset.

See also: GS_RasterOpen, GS_FileOpen, GS_RasterCreate

Parameters

[in] raster_id Raster handle in a GeoSci file.

Returns: TRUE is returned on success, FALSE otherwise.

Example: Close a raster whose handle was obtaiend earlier.
1 hid_t raster_id;

2 if(!GS_RasterClose(raster_id)) {

3 printf("Could not close raster.\n");

4 return;

5 }

hid_t GS_RasterCreate	(	hid_t	image_id,
		const_bstring	const_raster_name,
		int	raster_type,
		int	npixels,
		int	nlines,
		const_bstring	descriptor
	)

GS_RasterCreate create new image raster for a GeoSci Image.

See also: GS_RasterOpen, GS_RasterClose, GS_RasterDelete

Parameters

[in]	image_id;	A handle for an already-open image.
[in]	raster_name	The name of the raster channel to create.
[in]	raster_type	The type for the raster data. One of: DATATYPE_UI1 1 A single bit `GS_DATATYPE_UI8` 2 Unsigned 8-bit integer `GS_DATATYPE_SI8` 3 Signed 8-bit integer `GS_DATATYPE_CI8` 4 Complex 8-bit integer `GS_DATATYPE_UI16` 5 Unsigned 16-bit integer `GS_DATATYPE_SI16` 6 Signed 16-bit integer `GS_DATATYPE_CI16` 7 Complex 16-bit integer `GS_DATATYPE_UI32` 8 Unsigned 32-bit integer `GS_DATATYPE_SI32` 9 Signed 32-bit integer `GS_DATATYPE_CI32` 10 Complex 32-bit integer `GS_DATATYPE_CI64` 11 Complex 64-bit integer `GS_DATATYPE_R32` 12 32-bit Real number `GS_DATATYPE_R64` 13 64-bit Real number `GS_DATATYPE_C64` 14 Complex 64-bit floating-point number `GS_DATATYPE_C128` 15 Complex 128-bit floating point number `GS_DATATYPE_SI64` 16 Signed 64-bit integer
[in]	npixels	The x-dimension of the raster channel.
[in]	nlines	The y-dimension of the raster channel.
[in]	descriptor;	A string describing the raster contents.

Returns: The handle for the created raster is returned. This handle is less than zero if there is any error.

Example: Create the raster named "r7" for an image named "/image3" in an already-open GeoSci file. The raster should be a 32-bit-real image, with 1024 pixels X 512 lines.
1 hid_t file_id, image_id, raster_id;

2 bstring image_name = bfromcstr("/image3");

3 image_id = GS_ImageOpen(file_id,image_name);

4 bdestroy(image_name);

5 if(image_id < 0 ){

6 printf("GS_ImageOpen failure\n");

7 exit(-1);

8 }

9 bstring descriptor = bfromcstr("Howland-IR");

10 bstring name = bfromcstr("r7");

11 raster_id = GS_RasterCreate(image_id,name,GS_DATATYPE_R32,1024,512,descriptor);

12 bdestroy(descriptor);

13 bdestroy(name);

14 if(raster_id<0){

15 printf("GS_RasterCreate failure\n");

16 exit(-1);

17 }

18

19 .... do stuff ....

20

21 GS_RasterClose(raster_id);

22 GS_ImageClose(image_id);

Details: This function defaults the pixel size metadata: pixel_size__units="meter", pixels_size_x=1.0, pixel_size_y=1.0. These can be reset to valid values using the function GS_RasterPixelSize.

int GS_RasterCreateMetadata	(	hid_t	image_id,
		const_bstring	raster_name,
		int	raster_type,
		int	npixels,
		int	nlines,
		const_bstring	descriptor
	)

GS_RasterCreateMetadata fills the standard raster metadata attributes with the values that are passed in.

See also: ImageAdd()

Parameters

[in]	image_id	The ID of the image that contains this raster.
[in]	raster_name	A character string giving the name of the existing raster in the image.
[in]	raster_type	The type for the raster data. One of: DATATYPE_UI1 1 A single bit `GS_DATATYPE_UI8` 2 Unsigned 8-bit integer `GS_DATATYPE_SI8` 3 Signed 8-bit integer `GS_DATATYPE_CI8` 4 Complex 8-bit integer `GS_DATATYPE_UI16` 5 Unsigned 16-bit integer `GS_DATATYPE_SI16` 6 Signed 16-bit integer `GS_DATATYPE_CI16` 7 Complex 16-bit integer `GS_DATATYPE_UI32` 8 Unsigned 32-bit integer `GS_DATATYPE_SI32` 9 Signed 32-bit integer `GS_DATATYPE_CI32` 10 Complex 32-bit integer `GS_DATATYPE_CI64` 11 Complex 64-bit integer `GS_DATATYPE_R32` 12 32-bit Real number `GS_DATATYPE_R64` 13 64-bit Real number `GS_DATATYPE_C64` 14 Complex 64-bit floating-point number `GS_DATATYPE_C128` 15 Complex 128-bit floating point number `GS_DATATYPE_SI64` 16 Signed 64-bit integer
[in]	npixels	The x-dimension of the raster channel.
[in]	nlines	The y-dimension of the raster channel.
[in]	descriptor	A character string describing the image contents.

Returns: TRUE on success, FALSE on failure.

Example:

After creating a new raster named "r3" in an image named "datatake 34" in a file named "av1.h5", we must set the metadata for the raster before the raster object can be used. The descriptor is "SIRC-SLC data from SRL-1 over Greenland". The raster datatype is complex-integer, each 32 bits, with 1024 pixels along the x-direction, and 2048 lines along the y-dimension.

 hid_t file_id;
 hid_t image_id;
 bstring filename=bfromcstr("av1.h5");
 bstring access=bfromcstr("r+");
 file_id = GS_FileOpen(filename,access);
 bdestroy(filename);
 bdestroy(access);
 
 if(file_id > 0) {
    bstring image_name =bfromcstr("datatake 34");
    bstring image_descriptor = bfromcstr("sirc data");
    image_id = GS_ImageCreate(file_id,image_name,image_descriptor);
    bdestroy(image_name);
    bdestroy(image_descriptor);
    
    if(image_id>0){
       ... create a new dataset that represents the Raster...
 
       bstring name = bfromcstr("r3");
       bstring descriptor = bfromcstr("SIRC-SLC data from SRL-1 over Greenland");
       if(GS_RasterCreateMetadata(image_id,raster_name,GS_DATATYPE_CI32,
                                  1024,2048,descriptor){
          printf("success\n");
       }
       bdestroy(name);
       bdestroy(descriptor);
    }
    GS_ImageClose(image_id);
 }
 GS_FileClose(file_id);

Details:

The raster metadata is attached to the Dataset that holds the raster data. The raster metadata items are:
dataset_type (= "Raster"),
pixel_size_units (default is "meter"),
pixel_size_x,
pixel_size_y,
type,
npixels,
nlines,
descriptor,
creation_datetime,
last_update_datetime,
history,
and writeable.

Note that until the raster metadata is set up correctly the raster is not recognized as a valid GeoSci Raster object, and so most functions in this library will not operate on it successfully. Because of this, the raster creation functions, such as GS_RasterCreate, call this function as part of the creation process.

int GS_RasterDelete	(	hid_t	image_id,
		const_bstring	raster_name
	)

GS_RasterDelete deletes an existing raster.

See also: GS_ImageOpen, GS_RasterOpen, GS_RasterClose

Parameters

[in]	image_id	Handle of containing image.
[in]	raster_name	Name of raster to delete.

Returns: TRUE is returned on success, FALSE on failure.

Example: Delete a raster named "r3" in image named "/Channel_1" in a file named "test123.h5".
1 ...

2 hid_t file_id;

3 bstring name = bfromcstr("test123.h5");

4 bstring access = bfromcstr("r+");

5 file_id = GS_FileOpen(name,access);

6 bdestroy(name);

7 bdstroy(access);

8 if(file_id < 0) {

9 printf("Could not open file.\n");

10 return;

11 }

12

13 bstring image_name = bfromcstr("/Channel_1");

14 image_id = GS_ImageOpen(file_id,image_name);

15 bdestroy(image_name);

16 if(image_id < 0) {

17 printf("Could not open image.\n");

18 return;

19 }

20

21 bstring raster_name = bfromcstr("r3");

22 if(!GS_RasterDelete(image_id,raster_name)){

23 printf("raster deletion failed.\n");

24 bdestroy(raster_name);

25 return;

26 }

27 bdestroy(raster_name);

28 ...

hid_t GS_RasterOpen	(	hid_t	image_id,
		const_bstring	raster_name
	)

GS_RasterOpen opens existing raster dataset.

See also: GS_FileOpen, GS_RasterCreate, GS_RasterClose

Parameters

[in]	image_id	Image handle in a GEOSCI file
[in]	raster_name	Name of raster dataset to open.

Returns: A handle to the raster dataset is returned on success, while a value less than 0 is returned on failure.

Example: Open an image named "Channel_1" in a file named "test123.h5", and then open the raster, which is named "r1".
1 ...

2 hid_t file_id, image_id, raster_id;

3 bstring name = bfromcstr("test123.h5");

4 bstring access = bfromcstr("r+");

5 file_id = GS_FileOpen(name, access);

6 bdestroy(access);

7 bdestroy(name);

8 if(file_id < 0) {

9 printf("Could not open file.\n");

10 return;

11 }

12

13 bstring image_name = bfromcstr("/Channel_1");

14 image_id = GS_ImageOpen(file_id,image_name);

15 bdestroy(image_name);

16 if(image_id < 0) {

17 printf("Could not open image.\n");

18 return;

19 }

20

21 bstring raster_name = bfromcstr("r1");

22 raster_id = GS_RasterOpen(image_id,raster_name);

23 bdestroy(raster_name);

24 if(raster_id < 0) {

25 printf("Could not open raster.\n");

26 return;

27 }

28 ...

int GS_RasterPixelSize	(	hid_t	raster_id,
		int	func,
		double *	x_pixelsize,
		double *	y_pixelsize,
		bstring	pixel_units
	)

GS_RasterPixelSize reads/writes Raster Pixel Size.

See also: GS_RasterCreate

Parameters

[in]	raster_id	Handle to already-opened Raster in a GeoSci file.
[in]	func	Flag indicating whether to write the passed pixel size to the image metadata (GS_WRITE), or return the pixel size currently stored for the image (GS_READ).
[in,out]	x_pixelsize	Pixel ground X-size in `pixel_units' units.
[in,out]	y_pixelsize	Pixel ground Y-size in `pixel_units' units.
[in,out]	pixel_units	Pixel Size Units string.

Returns: TRUE is returned on success, FALSE otherwise.

Example: The following code prints out the current pixel size information, and then sets the pixel size to 1 meter by 1 meter.
1 hid_t raster_id;

2 double xsize, ysize;

3 bstring pixel_units=bfromcstr("");

4 ...

5 if(GS_RasterPixelSize( raster_id, GS_READ, &xsize, &ysize, pixel_units )){

6 printf( "Pixel Size was %g x %g %s\n",

7 xsize, ysize, bdata(pixel_units) );

8 }

9

10 xsize = 1.0;

11 ysize = 1.0;

12 bassigncstr(pixel_units,"meter");

13 if(GS_RasterPixelSize( raster_id, GS_WRITE, &xsize, &ysize, pixel_units )){

14 printf( "Pixel size reset to 1 x 1 Meters.\n" );

15 }

16 bdestroy(pixel_units);

17 ...

Details: This is useful for rasters that have no projection, or whose projection and spatial system are only loosely known. In other cases, using the projection information and the coordinates information in other metadata collections is preferred.

int GS_RasterSizeInfo	(	hid_t	raster_id,
		int *	npixels,
		int *	nlines
	)

GS_RasterSizeInfo returns the number of pixels and lines in a raster.

See also: GS_RasterPixelSize()

Parameters

[in]	raster_id	Handle for opened raster in a Geosci file.
[out]	npixels	Pointer to integer to be loaded with the number of image pixels.
[out]	nlines	Pointer to integer to be loaded with the number of image lines.

Returns: On success, TRUE is returned, otherwise FALSE is returned, and -1 for the values of both npixels and nlines.

Example: Provide the user with information about a previously opened raster. The program prints the number of pixels per line and lines per image.
1 hid_t fileid, image_id, raster_id;

2 int npixels, nlines;

3

4 // open the file:

5 bstring file_name = bfromcstr("blah.h5");

6 file_id = GS_FileOpen( file_name, bsstatic("r") );

7 if(file_id < 0){

8 printf("Can't open the file %s.\n",bdata(file_name));

9 return FALSE;

10 }// endif

11

12 // open the image

13 bstring image_name = bfromcstr("/Image1");

14 image_id = GS_ImageOpen(file_id, image_name);

15 if(image_id < 0){

16 printf("Can't open the image %s.\n",bdata(image_name));

17 return FALSE;

18 }// endif

19

20 //open the raster:

21 bstring raster_name = bfromcstr("raster4");

22 raster_id = GS_RasterOpen(image_id,raster_name);

23 if(raster_id < 0){

24 printf("Can't open the raster %s.\n",bdata(raster_name));

25 return FALSE;

26 }// endif

27

28 if(GS_RasterSizeInfo( raster_id, &npixels, &nlines )){

29 printf( " Pixels: %d\n Lines: %d\n",

30 npixels, nlines );

31 } else {

32 printf("Can't get Raster size information.\n");

33 }

34 GS_RasterClose(raster_id);

35 GS_ImageClose(image_id);

36 GS_FileClose(file_id);

int GS_RasterTypeIsComplex ( int datatype )

GS_RasterTypeIsComplex returns TRUE for complex types.

See also: GS_GetRasterTypeAsString, GS_RasterTypeIsInteger, GS_GetRasterTypeAsInteger, GS_GetRasterTypeNumbytes

Parameters

[in] datatype An integer representing a GeoSci datatype. Valid datatypes:
GS_DATATYPE_UI1 1 A single bit
GS_DATATYPE_UI8 2 Unsigned 8-bit integer
GS_DATATYPE_SI8 3 Signed 8-bit integer
GS_DATATYPE_CI8 4 Complex 8-bit integer
GS_DATATYPE_UI16 5 Unsigned 16-bit integer
GS_DATATYPE_SI16 6 Signed 16-bit integer
GS_DATATYPE_CI16 7 Complex 16-bit integer
GS_DATATYPE_UI32 8 Unsigned 32-bit integer
GS_DATATYPE_SI32 9 Signed 32-bit integer
GS_DATATYPE_CI32 10 Complex 32-bit integer
GS_DATATYPE_CI64 11 Complex 64-bit integer
GS_DATATYPE_R32 12 32-bit Real number
GS_DATATYPE_R64 13 64-bit Real number
GS_DATATYPE_C64 14 Complex 64-bit floating-point number
GS_DATATYPE_C128 15 Complex 128-bit floating point
GS_DATATYPE_UI64 16 Unsigned 64-bit integer
GS_DATATYPE_SI64 17 Signed 64-bit integer

Returns: TRUE is returned for complex types, FALSE for scalar types and ERROR otherwise.

Example: Query if the type GS_DATATYPE_CI32 is a complex type:
1 int result;

2 result = GS_RasterTypeIsComplex(GS_DATATYPE_CI32);

3 if( result == TRUE ) {

4 printf("It's a complex type\n");

5 } else if( result == FALSE ){

6 printf("It's a scalar type\n");

7 } else {

8 printf("Error!\n");

9 }

int GS_RasterTypeIsInteger ( int datatype )

GS_RasterTypeIsInteger returns TRUE for integer types.

See also: GS_GetRasterTypeAsString, GS_GetRasterTypeAsInteger, GS_GetRasterTypeNumbytes

Parameters

[in] datatype An integer representing a GeoSci datatype. Valid datatypes:
GS_DATATYPE_UI1 1 A single bit
GS_DATATYPE_UI8 2 Unsigned 8-bit integer
GS_DATATYPE_SI8 3 Signed 8-bit integer
GS_DATATYPE_CI8 4 Complex 8-bit integer
GS_DATATYPE_UI16 5 Unsigned 16-bit integer
GS_DATATYPE_SI16 6 Signed 16-bit integer
GS_DATATYPE_CI16 7 Complex 16-bit integer
GS_DATATYPE_UI32 8 Unsigned 32-bit integer
GS_DATATYPE_SI32 9 Signed 32-bit integer
GS_DATATYPE_CI32 10 Complex 32-bit integer
GS_DATATYPE_CI64 11 Complex 64-bit integer
GS_DATATYPE_R32 12 32-bit Real number
GS_DATATYPE_R64 13 64-bit Real number
GS_DATATYPE_C64 14 Complex 64-bit floating-point number
GS_DATATYPE_C128 15 Complex 128-bit floating point
GS_DATATYPE_UI64 16 Unsigned 64-bit integer
GS_DATATYPE_SI64 17 Signed 64-bit integer

Returns: TRUE is returned for integer types, FALSE for floating-point types and ERROR otherwise.

Example: Query if the type GS_DATATYPE_CI32 is an integer type:
1 int result;

2 result = GS_RasterTypeIsInteger(GS_DATATYPE_CI32);

3 if( result == TRUE ) {

4 printf("It's an integer type\n");

5 } else if( result == FALSE ){

6 printf("It's a floating-point type\n");

7 } else {

8 printf("Error!\n");

9 }

herr_t GS_SetCacheSize	(	hid_t	file_id,
		size_t	cache_size
	)

GS_SetCacheSize sets the metadata cache size for a GeoSci datafile.

Parameters

[in]	file_id	File handle for GeoSci datafile
[in]	cache_size	Size in bytes for the metadata cache. 1048576 (1 MByte) is a good default.

Returns: A non-negative integer is returned on success, while a negative integer is returned on failure.

Example: Set the cache size to be 1MByte:
1 hid_t file_id;

2 if(GS_SetCacheSize(file_id,1048576) < 0){

3 printf("Error setting cache size.\n");

4 }

int GS_SetStringAttribute	(	hid_t	object_id,
		const_bstring	name,
		const_bstring	value
	)

GS_SetStringAttribute sets the value of a string attribute for a given object.

See also: GS_GetStringAttribute()

Parameters

[in]	group_id	The opened object where the attribute is stored.
[in]	name	The name of the attribute variable.
[in]	value	The value of the variable to set.

Returns: TRUE on success, FALSE on failure.

Example:: Set the group type attribute:
1 bstring group_type=bfromcstr("");

2 hid_t object_id;

3 bassigncstr(group_type,"unknown type");

4 if(!GS_SetStringAttribute(object_id,bsstatic("grouptype"),group_type)){

5 printf("Unable to set group-type string\n");

6 } else {

7 printf("Group-type successfully set.\n");

8 }// endif

9 ... use group_type ...

10 bdestroy(group_type);

int GS_SplitHistory	(	const_bstring	history_string,
		bstring	front,
		bstring	back
	)

GS_SplitHistory splits history string into front and back.

See also: GS_AppendHistory(), GS_AbortedHistory()

[in] history_string: The input history string.

[out] front: The output front of the history string, with the last line, if any, stripped off. On input, this must be a valid bstring.

[out] back: The output back of the history string, containing the last line, if any. On input, this must be a valid bstring.

Returns: TRUE on success, FALSE on failure.

Example:: Given a history string like:
"line1;\nline2;\nline3;\n"
This function returns:
front = "\line1;\nline2;\n" back = "line3;\n" This is programmed as:
1 bstring history=bfromcstr("line1;\nline2;\nline3;\n");

2 bstring front =bfromcstr("");

3 bstring back =bfromcstr("");

4

5 GS_SplitHistory(history,front, back);

6

7 ... use front and back ...

8

9 bdestroy(history);

10 bdestroy(front);

11 bdestroy(back);

Details:

The history string is made up of lines delimited by ";\n". There are several cases:

If the history string is empty, then 2 empty strings are returned.

li If the history string is non-empty, but has no ";\n" delimiters, then the returned front string is empty, and the back string is this string, with a ";\n" appended to it.

If the history string has 1 line, then the returned front string is empty, and the back string is this 1 line.

In all other cases, all but the the last line is copied to the front string, and the last line is copied into the back string.

int GS_UpdateMetadata	(	hid_t	object_id,
		const_bstring	name,
		bstring	value
	)

GS_UpdateMetadata update a metadata item for the given object.

See also: GS_AppendMetadata

Parameters

[in]	object_id	ID of GeoSci object to modify. Can be a file, an image, etc.
[in]	name	The name of the metadata variable to modify.
[in]	value	The new value for the metadata variable.

Returns: TRUE on success, FALSE on failure.

Example:: Change the descriptor metadata for an image to "Angkor Wat, Cambodia".
1 hid_t image_id;

2 bstring name = bfromcstr("/image45");

3 image_id = GS_ImageOpen(file_id,name);

4 bdestroy(name);

5 if(!image_id) {

6 printf("Failed to open the image\n");

7 }

8 bstring descriptor = bfromcstr("descriptor");

9 bstring descriptor_value = bfromcstr("Angkor Wat, Cambodia");

10 if(!GS_UpdateMetadata(image_id,descriptor,descriptor_value))){

11 printf("Failed to modify image descriptor\n");

12 }

13 bdestroy(descriptor);

14 bdestroy(descriptor_value);

int GS_ValidID ( hid_t id )

GS_ValidID returns whether the given object-id is a valid identifier.

See also: GS_FileCreate()

Parameters

[in] id An identifier that may have been returned from one of the other routines in the library, possibly referring to a file, an image, or some other object of interest in the file.

Returns: TRUE is returned if the identifier is valid, FALSE otherwise.

Exmaple:: We have obtained an identifier for an image object, and we wish to see if it is still valid:
1 hid_t id;

2 if(GS_ValidID(id)){

3 printf("The id is valid\n");

4 } else {

5 printf("The id is invalid\n");

6 }

int GS_ValidMetadataName	(	int	object_type,
		const_bstring	name
	)

GS_ValidMetadataName check if the name is a valid metadata item for the given object type.

See also: GS_FileCreate()

Parameters

[in]	object_type	An integer giving the type of object this metadata variable refers to. Valid object types are: `GS_OBJECT_TYPE_METADATA_GROUP` 1 `GS_OBJECT_TYPE_IMAGE` 2 `GS_OBJECT_TYPE_VECTOR` 3 `GS_OBJECT_TYPE_VECTOR2D` 4 `GS_OBJECT_TYPE_VECTOR3D` 5 `GS_OBJECT_TYPE_TIN` 6 `GS_OBJECT_TYPE_MESH2D` 7 `GS_OBJECT_TYPE_MESH3D` 8 `GS_OBJECT_TYPE_RASTER` 9 `GS_OBJECT_TYPE_IFILE` 10 `GS_OBJECT_TYPE_METADATA_DATASET` 12 `GS_OBJECT_TYPE_METADATA_IFILE` 13
[in]	name	A character string giving the name of the metadata variable to query.

Returns: TRUE is returned if the name is a valid metadata variable, FALSE otherwise.

Example:: Make sure that descriptor is a valid metadata item for an image before updating its value:
1 bstring name = bfromcstr("descriptor");

2 if(!GS_ValidMetadataName(GS_OBJECT_TYPE_IMAGE, name)){

3 printf("not a valid image metadata variable.\n");

4 }

5 bdestroy(name);

Details:: Because the metadata updating functions will not only update, but also create new metadata items, this function is used to prevent mis-spellings of valid metadata items, and also to prevent accidental creation of new metadata items.

int GS_VectorCreateMetadata	(	hid_t	file_id,
		const_bstring	vector_name,
		const_bstring	descriptor
	)

GS_VectorCreateMetadata creates vector metadata.

See also: GS_VectorCreate()

Parameters

[in]	file_id	The file ID.
[in]	vector_name	A character string giving the name of the image.
[in]	descriptor	A character string describing the vector contents.

Returns: TRUE on success, FALSE on failure.

Example:

After creating a new vector named "hydrology" in a file named "av1.h5", we must set the metadata for the vector object before it can be used. The descriptor is "water boundaries".

 hid_t file_id;
 bstring name = bfromcstr("av1.h5");
 bstring access = bfromcstr("r+");
 file_id = GS_FileOpen(name,access);
 bdestroy(name);
 bdestroy(access);
 if(file_id > 0) {
    ... create a group with a dataset in it that represent the vector information...
    bstring vname = bfromcstr("hydrology");
    bstring vdescriptor = bfromcstr("water boundaries");
    if(GS_VectorCreateMetadata(file_id,vname,vdescriptor){
       printf("success\n");
    }
    bdestroy(vname);
    bdestroy(vdescriptor);
 }

Details:

The vector metadata is attached to the Group within which the vector Dataset is stored. The vector metadata items are: grouptype (= "Image"), descriptor, creation_datetime, last_update_datetime, history, writeable and spatialref.

Note that until the vector metadata is set up correctly the image is not recognized as a valid GeoSci Vector object, and so most functions in this library will not operate on it successfully. Because of this, the vector creation function, GS_VectorCreate calls this function as part of the creation process.

Macros

Typedefs

Functions

Function Documentation