RECORD_TYPE           = "STREAM"
PRODUCT_ID            = "PDSLIB_README"

OBJECT                = TEXT
  PUBLICATION_DATE    = 2006-03-01
  NOTE                = "Introduction to the PDSLIB IDL library"
END_OBJECT            = TEXT
END

=======================================================
==           Fairwood PDS IDL Library                ==
=======================================================

License: 

(C) 2004-2010 Stubbe F. Hviid
This library is licensed for the use of running the OSIRIS calibration pipeline.
All other rights are reserved!


Prerequisites:
--------------

The library has been developed using IDL 6.1 - 7.0 on the windows platform.
The library will likely work on other platforms, but is only supported on the
above mentioned platform.


--------------------------------------------------------
--- Simple usage! - for details see function headers ---
--------------------------------------------------------


To read a PDS file:
-------------------

p_read, filename, header, data 

       filename is the path to the PDS/vicar   file
       header is the output header structure
       data is the output data matrix

example:   p_read, pickfile(), header, data
           tvscl, data


To write a PDS file:
--------------------

p_write, filename, header, data

       filename is the path to output PDS file
       header is the header of the image to be saved
       data is the image matrix to be saved (CAN BE ANY SCALAR DATATYPE EXCEPT COMPLEX)

Example:
	header = p_newhead()
	p_write, pickfile(), header, dist(250,250)



To create a new pds header
--------------------------

header = p_newhead()


To access header information
----------------------------

value = p_value(header, tag)

	header is a valid PDS header structure as returned by p_read or p_newhead
	tag is the header id of the item to be extracted

	tag is a text strung with the following syntax:

	tag = '<group1>.<sub group 2>. ... .<item>

Example:
	print, p_value(header, 'SR_ACQUIRE_OPTIONS.EXPOSURE_DURATION')  will return the exposure time of an OSIRIS image

        SR_ACQUIRE_OPTIONS is the group and EXPOSURE_DURATION is the item

	Items can have a namespace identifier associated (ROSETTA:  for OSIRIS images)
	it is not required to specify this name space, thus

            'SR_ACQUIRE_OPTIONS.ROSETTA:COMMANDED_FILTER_NAME'
        is the same as
            'SR_ACQUIRE_OPTIONS.COMMANDED_FILTER_NAME'

tag can also refer directly to a group spicifier. In this case the content of the full group (with all sub groups) will be returnes as an IDL structure.


	Example:   help, p_value(header, 'SR_ACQUIRE_OPTIONS')    is valid


to change and add new items to a PDS header
-------------------------------------------

p_setvalue, header, tag, value

	header is the PDS header structure to be modified
	tag    is the path to the header ietms to me added/modified (See above for syntax)
	value  is the value of the item to be set.

	value can be text strings or scalars (integers or floats)   or arrays of strings or scalars	 or an IDL structure

	if tag refers to an existing value the existing value is changed
	if tag refers to a new item all required groups and items are automatically created


	Example:
	p_setvalue, header, 'SR_ACQUIRE_OPTIONS.EXPOSURE_DURATION', 10		Set the osiris exposure time to 10 seconds

	p_setvalue, header, 'NEWGROUP.NEWSUBGROUP.ITEM', 'Hello World'
		will create a new group 'NEWGROUP' with subgroup 'NEWSUBGROUP' with member item 'ITEM' with text string value 'Hello World'