%******* The Earth Object Data System ***********************
%
% A) CONCEPTS
% 
%   Earth Objects are special data structures designed for use in Matlab 
% to storecomplex earth science datatypes. Like everything else in Matlab, 
% Earth Objectsare matricies which can grow or shrink as needed. They are 
% unique in that special meaning is attached to select elements which 
% allows their interpretation as earth data types. As an example, one might 
% wish to have a datatype called named matrix' which could be used as a 
% matlab matrix with a string providing a descriptive name. Suppose the 
% matrix we wish to give a name to has m rows and n columns and the name 
% is to be k characters in length. Then we could define a named matrix as a 
% Matlab column vector of length k + 2 +m*n which the following storage 
% scheme:
%	
%	rows 1 through k .... will contain the name converted from a Matlab
%		 string to integers
%	row k+1 ... will contain the number of data rows: m
%	row k+2 ... will contain the number of data columns: n
%	rows k+3 through k+m*n+2 ... will contain all of the elements of the
%		 m by n matrix strung out in columnwise fashion.
%
%   (Note that k would have to be a constant for all such objects and can 
% be considered as the maximum name length. A sensible value for k might 
% be 30.)
%   Then, we would have to agree never to operate numerically directly 
% on such a Matlab vector. Instead, we could build special access routines 
% called nmget and nmset which would get and set the values in such a 
% named matrix. The syntax for nmset might be something like:
%	object_out = nmset(object_in, 'string', value)
% where 
%	object_in is the input named matrix object
%	object_out is the output named matrix object (This will usually be
%		the same Matlab variable as object_in)
%	'string' is a Matlab string specifying which field we are setting. It
%		could have any of the values: 'name', 'datarows', 'datacols', 
%		and 'data'.
%	value is a Matlab variable giving the value to set into the
%		appropriate spot in the named matrix.
%		
% Similarly, nmget might work something like
%	value = nmget(object_in,'string')
%		
% where the meanings are the same as before. If my_nm is the Matlab 
% variable namefor such a named matrix, then some examples of using nmget 
% and nmset might be:
%	
%	my_nm = nmset(my_nm,'name','Fred') ... change the name to 'Fred'
%	your_nm = nmset(my_nm,'name','Matilda') ... change the name to
%		'Matilda' but output the result into a new named matrix with
%		the variable name your_nm. my_nm remains unchanged.
%	my_nm = nmset(my_nm,'data',some_matrix) ... change the matrix
%		data to the values in the matrix some_matrix. Presumably, this
%		would also set the values of 'datacols' and 'datarows' as
%		appropriate.
%	thename = nmget(my_nm,'name') ... get the name of my_nm (the first
%		k rows) and output it as a Matlab string.
%	thedata = nmget(my_nm,'data') ... get the matrix of data from my_nm
%		for plotting or crunching. This will automatically reshape it
% 		into theproper size by getting the values in 'datarows' and 
%		'datacols'.
%
%   It is easy to see that this logic can be extended to build very 
% complex objects which can contain all earth science information relevant 
% to a given project. In a direct sense, we have designed a method for 
% building "abstract data types" within Matlab which is one of the major 
% goals of object oriented programming (oop). The development of Matlab 
% software, including i/o routines and links to other software systems has a 
% number of advantages including:
%	-  Data organization: the encapsulation of all data with a common
%		theme into a single Matlab variable greatly simplifies file i/o
%		and the processof providing that data to a Matlab application.
%	- Matlab applications can be independent of the data internals: So
%		long as applications are developed which expect such earth
%		objects as input data and which only interact with the objects
%		through their "get" and "set" methods; then, these applications
%		are independent of the detailed internal structure of the data
%		objects.
%
%   These benefits mean that Matlab applications can evolve 
% independently of the evolution of the data objects which leads to much 
% more robust software. And, such applications can exchange data more 
% simply without extensive user intervention.
%	
% B) Current Object Zoology
% 
%   Currently, two major types of objects exist with and a number more 
% are under development. In existence now are "random objects" and "gridded 
% objects" which are created with the Matlab routines "randobj" and 
% "gridobj" and whose get and set methods are "objget" and "objset". In 
% development are "container objects" (objects which will contain other 
% objects) and specific objects to model wells and their varied information.
% 	
%   Gridded objects may be used to store any earth information which is 
% sampled on a regular x-y grid (1-D or 2-D grids). Examples include seismic 
% traces, gridded gravity and magnetics data, gridded reservoir data, etc. A 
% single gridded object may contain an unlimited number of gridded datasets 
% though all must have the same geometry. (The object grows as needed to 
% accomodate new datasets.) Each dataset has a unique 30 character 
% (maximum) name, a create and last modified date and a protection flag to 
% guard against accidental erasure. The object itself has fields for such 
% things as object creation date, last modified date, geometry description, 
% object name (unlimited length), and more. The geometry is typically 
% specified in local coordinates (numbers ranging from 0 to 100 or so) but 
% global coordinates (probably UTM's) are supported too. Gridded objects are 
% created directly with "gridobj" though "readzmap" also creates gridded 
% objects by calling "gridobj" internally. Gridded objects have an assumed 
% (x,y) coordinate system in which x varies along the rows (is constant for 
% each column) and y varies along the columns (is constant for each row).
% 
%   Random objects are used to store earth datasets which are sampled 
% at irregular locations such that (x,y) coordinates must be stored for each 
% sample point. As with gridded objects, any number of datasets with 
% similar geometry may be stored. There is no assumed coordinate system 
% for random objects; rather, x and y coordinates must be explicitly set. It 
% is a good idea when doing so to give the coordinates the names 'x' and 'y' 
% because many tools look for such datasets when needing coordinate 
% information. For example, "objget" looks for datasets called 'x' and 'y' 
% when asked to provide 'xglobal' or 'yglobal'.
% 	
%   In development are container objects which are designed to store an 
% arbitrary number of other objects and a number of other objects based on 
% containers such as wells, horizons, cross sections, ...
% 	
% C) Possible Settings in Random and Gridded Objects
%
%	Fields in random and gridded objects are set by calling "objset". The 
% syntax for callin "objset" is summarized as:
%	object = objset( objin, item, value);
%	object = objset( objin, item, value, datanum);
%	object = objset( objin, item, value, dataname);
%
%    OBJSET accepts an EarthObject (created by RANDOBJ, GRIDOBJ) and 
% sets the values of one of it's items. If the item already exists, then its 
% values are replaced; otherwise a new item is added to the object and its 
% values inserted. New items are assumed to be data (as opposed to headers) 
% and must be the same size and geometry as other data items already in the 
% object. The identity of header fields in the object is fixed so new header 
% information cannot be added; however, the existing headers can be changed 
% (updated) at any point. A data item may be protected from accidental 
% overwrite by setting its preserve flag to 'on'. The first form of the 
% command is used most often and sets items that are not specific to a 
% particular dataset within the object. 
%
% Examples: (let myObj be an existing object)
%    myObj = objset(myObj, 'username', 'barney'); ... change the username
%            to barney
%  yourObj = objset(myObj,'username','barney'); ... as above but create a
%            new object
%    myObj = objset(myObj,' Leduc ',newGrid); ... a grid referred to by the
%            matlab variable "newGrid" is put in the object and named ' Leduc '
%    myObj = objset(myObj,'protect','on',' Leduc '); ... the ' Leduc ' grid 
%            is protected.
%    myObj = objset(myObj,'protect','off',' Leduc '); ... the ' Leduc ' grid 
%            is unprotected.
%    myObj = objset(myObj,'protect','on',3); ... the third grid is 
%            unprotected.
%
% Argument definitions:
%    objin = the variable name of the object to be updated
%     item = a string specifying the item to be set (max of 30 characters)
%    value = the value(s) of the item
%  datanum = the sequential number of one of the data fields in the 
%            object
% dataname = string giving the name of one of the data fields in the 
%            object
%   object = the output object. Normally this will be the same matrix as 
%            objin
% 
%	Possible specifications for item strings include any of the 
% following:
% string ........... field which will be set
%--------------------------------------------------------------
% 'objvernum' .... a version number referring to the object software which
%	created the object. Older objects may not work directly with newer 
%	software and will require conversion. You should not attempt to 
%	change this value.
% 'objcreate' .... object creation date returned as a sequence of 6 integers.
%	The key is: yy mm dd hh mn ss where yy is year, mm is month, dd is 
%	day, hh is hour, mn is minute, and ss is seconds. GRIDOBJ and 
%	RANDOBJ set this field automatically when an object is created. The 
%	matlab command: fix(clock) will return a six integer field 
%	appropriate for any object date field.
% 'objmodified' .... date the object was last modified. OBJSET will update 
%	this automatically anytime a field in the object is set or a new one 
%	added. See 'objcreate' above for a description of the date format.
% 'objtype' .... short string giving the object type (grid or rand etc) (Set 
%	automatically by GRIDOBJ and RANDOBJ)
% 'datatype'.... short string giving the data type (seis, mag, grav etc)
%	(Usually set by GRIDOBJ or RANDOBJ)
% 'username' .... 6 character string giving a user id assicuated with the 
%	object.
% 'name'.... possibly long string giving the object name
%	(Usually set by GRIDOBJ or RANDOBJ)
% 'xaxisname' ... max of 10 characters giving the name of the x axis
% 'yaxisname' ... max of 10 characters giving the name of the y axis
% 'north' ... azimuth angle in degrees of true north. 0 is along the
%	x axis and 90 along the y axis
% 'east' ... azimuth angle in degrees of true east.
% 'datacols'.... the number of columns in the data matrix
%	(Usually set by GRIDOBJ or RANDOBJ)
% 'datarows'.... the number of rows in the data matrix
%	(Usually set by GRIDOBJ or RANDOBJ)
% 'delx'.... the spacing between columns in physical units
%	(Usually set by GRIDOBJ, not used by RANDOBJ)
% 'dely'.... the spacing between rows in physical units
%	(Usually set by GRIDOBJ, not used by RANDOBJ)
% 'xnot'.... the coordinate of the first column in physical units
%	(Usually set by GRIDOBJ, not used by RANDOBJ)
% 'ynot'.... the coordinate of the first row in physical units
%	(Usually set by GRIDOBJ, not used by RANDOBJ)
% 'globorigin' .... a 1 by 2 vector giving global coordinates [x,y] for the 
%	data origin. See discussion of local and global coordinates below.
% 'xyscale' .... scalar relating local and global coordinates
% 'xyrotate' .... rotation angle (degrees) relating local and global 
%                 coordinates.
%
% Additionally, any of the strings returned by objget(anyObject,'fieldnames') 
% or objget(anyobject,'namesmatrix') may be used as item strings. For 
% example, suppose objget(myObject,'fieldnames') returns the string: 
% wabamun|peace river|leduc|nordegg
% Then, the data grid named 'peace river' may be set by
%	myObject = objget(myObject,'peace river', peaceGrid); ... peaceGrid is 
%		a matlab matrix containing the z values of the grid 'peace